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1. Introduction 

1.1 Purpose 

In this document we introduce the Lisp programming environment of the Symbolics Lisp 
Machine. Using a single example program, we present one style of interacting with that 
environment in developing Lisp programs. We do not prescribe a "best" style of programming 
on the Lisp Machine. Rather, we suggest some techniques and combinations of features that 
expert Lisp Machine programmers advocate. You might find these techniques useful in 
developing a comfortable and efficient Lisp Machine programming style of your own. 

1.2 Prerequisites 

This document is for you if you will be writing or maintaining Lisp programs and have recently 
begun to use a Lisp Machine. The document will be most useful if you have some experience 
writing Lisp programs and are familiar with basic features of the Lisp Machine. The document 
is not a survey of Lisp Machine faciliti^ a reference manual, or a Lisp primer. You might 
find the following Symbolics publications helpful when reading this document: 

• Liqf Machine Summary 

• Program Development Help Facilities 

• Lisp Machine Manual 

• An up-to-date set of release notes 

1.3 Scope 

We focus in this document on interaction between programmers and the Lisp Machine. We 
present some ways of using Lisp Machine features that you might find helpful at each stage of 
program development. We mention some broad issues of style in designing programs, including 
modularity and efficiency, but we do not explore program structure in any depth. We do not 
discuss matters of style in using Lisp, such as appropriate uses for structures and flavor. 

This document corresponds to the Symbolics 3600. Some key bindings and symbol names are 
different on the Symbolics LM-2. 

1.4 Method 

We derived the methods we describe here by working with Lisp Machine programmers at 
Symbolics. Some of these progranuners were early developers of the machine itself. Their 
styles vary. Like most programmers, they generally do not follow a simple textbook sequence 
of designing, coding, compiling, debugging, recompiling, testing, and debugging again. Instead, 
they develop programs in repeated cycles, each a sequence of editing, compiling, testing, and 
debugging. These cycles are often nested. For example, an error in testing a program invokes 
the Debugger; from the Debugger the programmer types Lisp forms or calls the editor to 
change and recompile code; an error in retesting code from the Debugger invokes the Debugger 
again. 
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1.5 Features 

Symbolics developers have designed the Lisp Machine to accommodate a relatively spontaneous 
and incremental progranmiing style. Five Lisp Machine features make up an integrated 
prc^amming environment. 

• TIk 2^talisp environment. The Lisp system code allows you to write 
programs that are extensions of the environment itself. You can often 
produce complex programs with comparatively little new code. 2>talisp 
flavors let you build data structures with complex modular combinations of 
associated procediires and state information. 

• The window system. Windows permit you to shift rapidly among such 
activities as editing, evaluating Lisp, and debugging. You can suspend an 
activity in one window, switch to another, and return to the first without 
losing its state. You can display several activities on the same screen. 
Because the window system is itself implemented with Zetalisp flavors, you 
can modify or create windows for special displays. 

• The Zmacs text editor. Zmacs has sophisticated means of keeping track of 
Lisp syntax. It interacts with the Zetalisp environment, letting you find out 
about existing code and incorporate it into yoiu* programs. Unlike some 
structure editors, Zmacs allows you to leave deHnitions incomplete until you 
are ready to evaluate or compile them. 

• Dynamic compiling, linking, and loading. The compiler is always loaded. 
You can use single-keystroke commands to compile and load source code 
from a Zmacs buffer. You can write, compile, test, edit, and recompile code 
in sections. When you recompile a functicm definition, the function's callers 
use the new definition. 

• Interactive debugging. Errors invoke the Debugger in their dynamic 
environments. From the Debugger you can examine the stack, change 
values of variables and arguments, call the editor to change and recompile 
source code, and reinvoke functions. 

1.6 Organization 

The sequence of steps in developing a program on the Lisp Machine is too complex to mirror 
in the linear organization of a document. We emphasize the cyclical course of program 
development, but we have organized he document in a simple way. We present the main 
programming sequence in the next three chapters. These deal simply with writing and editing, 
evaluating and compiling, and debugging code. We discuss particular Zetalisp functions, Zmacs 
commands, and other features where they appear most useful or where they present alternatives 
to common techniques. 

The next three chapters require virtually no knowledge of flavors or the window system. But 
knowing about flavors and windows is essential to advanced use of the Symbolics Lisp Machine. 
Chapter 5 presents some simple uses of flavors and windows and some programming aids for 
working with them. 

Throughout, we use as an example the development of a single program that draws the 
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recursive arrows in the cover design for this document. Sandy Schafer and Bernard LaCasse of 

Schafer/LaCasse created the original design. Richard Bryan of Symbolics wrote and we revised 

a Lisp program that simulates it The complete code appears in appendixes A (page 133) 

and B (page 147) and in the files SYS: EXAMPLES; ARROW-CALC LISP and 

SYS: EXAMPLES; ARROW-OUT LISP. (To run the program, load 

SYS: EXAMPLES; ARROW.) A reproduction of the design produced on a Symbolics LGP-1 

Laser Graphics Printer appears in appendix C (page 165). 

Many of the techniques and facihties we mention are helpful at more than one stage of 
program development Conversely, the Lisp Machine provides many paths for accompluhing 
tasks at each stage. As programmers at Symbolics gladly acknowledge, there is more than one 
way to do almost anything on the Lisp Machine. 

1 .7 Notation Conventions 

Modifier keys are designed to be held down while pressing other keys. They do not themselves 
transmit characters. A combined keystroke like METR-X is pronounced "meta x** and written as 
m-X. This notation means press the META key and, while holding it down, press the X key. 

Modifier keys are abbreviated as follows: 
Kq^ Abbrenation 
CTRL c- 
METfl IB- 
SUPER s- 
HYPER h- 
SHIFT sh- 

The keys with white lettering (like X or SELECT) all transmit characters. Combinations of 
these keys are meant to be pressed in sequence. This sequence is written as, for example, 
SELECT L. This notation means press the SELECT key, release it, and then press the L key. 

This document uses the following notation convention: 

Appearance in document Rq>resenting 

send, chaos:host-op Printed representation of Lisp objects in running text. 

RETURN, ABORT, c-F Keyboard keys. 

SPRCE Space bar. 

login Literal type-in. 

(make-synbol "foo") Lisp code «campl». 

(f anction-nane argl areZS Syntax description of the invocation of fanction-name. 

argl Argument to the function f anctlon-name, usually expressed as a 

word that reflects the type of argument (c.g., string). 
are2 Optional argument; you can leave it out. 

Undo, Tree Edit Any Command names in Zmacs and Zmail appear with initial letter of 

each word capitalized. 
Insert File (»-X) Extended command names in Zmacs and Zmail. Use m-X to 

invoke one. 
[Map Over] Menu items. 

(L), (R2) Mouse cUcks: L=left, L2=double click left, M=middle, 

M2=double click middle, R=right, R2=double click right 
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Mouse commands use notations for menu items and mouse clicks in the following ways: 

1. Square brackets delimit a mouse command. 

2. Slashes (/) separate the members of a compound mouse command. 

3. The standard clicking pattern is as follows: 

• For a single menu item, always click left. For example, the following two 
commands are exactly the same: 

[Previous] 
[Previous (L)] 

• For a compound command, always click right on each menu item except the 
last, where you click left. For example, the following two compound 
commands are exactly the same: 

[\fap Over / Move / Hardcopy] 

[Map Over (R) / Move (R) / Hardcopy (L)] 

4. When the notation does not follow the standard, it shows explicitly which 
button to click. For example: 

[Map Over / Move (M)] 
[Previous (R)] 

In the sections of this document that develop the Lisp code for the example prc^am, we use 
change bars to distinguish new or changed code from code that we have ah-eady presented. 
Whenever we display a line of code that has not appeared before, and whenever we change a 
line of code that has already appeared, we place a vertical bar (|) next to that line in the left 
margin. This bar is not part of the code itself. In the following example, we change two lines 
of the definition of draw-blg-arrow: 

(defun draw-blg-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multlple-value-blnd 
(•plx« 'ply* •p2x» "pZy* 'pSx* "pSy* 'pex* 'pey*) 

(compute-arrowhead-points) 
;; Determine coordinates of shaft vertexes 
(multlple-value-blnd ('pSx* 'pSy* *p4x* •p4y«) 
( compu te-arrow-shaf t-po 1 n ts ) 
(draw-blg-outllne) ;0ut11ne arrow 

(when 'do-the-strlpes* 
(stripe-arrowhead))))) ; Stripe head 
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2. Writing and Editing Code 



Symbolics Lisp Machine programmers seldom write programs in sequence, from beginning to 
end, before testing them. They often leave definitions incomplete, skip to other definitions, and 
then return to finish the incomplete forms. They search for existing code to incorporate into 
new programs. They edit their work frequently, changing code while writing, testing, and 
maintaining programs. 

In this chapter we discuss Lisp Machine features, particularly Zmacs commands and Zetalisp 
functions, that make this style natural. Many of these features are useful at other stages of 
programming as well: Editing techniques are important in program maintenance, and methods 
of learning about existing code are helpful in debugging. 

To illustrate programming methods, we develop a program that draws the recursive arrow 
design that appears on the cover of this document. (The program does not draw the horizontal 
stripes outside the large arrow.) We produce the figure on a Symbolics LGP-1 Laser Graphics 
Printer, a Lisp Machine screen, or a file. We develop the program in four stages, beginning 
with simple procedures to outline the arrows and progressively modifying the code to refine the 
figure: 

1. Drawing the borders of the large arrow and of the smaller recursively 
drawn arrows that it encloses 

2. Drawing the diagonal stripes within the figure, but with uniform thickness 
and spacing 

3. Changing the stripes to vary in thickness and spacing 

4. Writing the routines that control the output destination 

Appendixes A (page 133), B (page 147), and C (page 165) contain the code for the sample 
program and a reproduction of the LGP image the program produces. 

2.1 Before You Begin 

Use the Zmacs text editor to write and edit programs. Zmacs has many features that provide 
information about Zmacs commands, existing code, buffers, and files. Two features are 
generally useful: the HELP key and completion. (See Program Development Help Facilities for 
details.) 

2.1.1 HELP 

Pressing the KCLP key in a Zmacs editing window gives information about 
Zmacs commands and variables. The kind of information it displays 
depends on the key you press after IHELP. 

Reference 

HELP ? Display a summary of VEiP options. 

HELP R Displays names, key bindings, and brief descriptions of 

commands whose names contain a string you specify, 
(fl refers to "apropos".) 
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HELP C Displays the name and brief description of a command 

bound to a key you specify. 

I^LP D Displays long documentation for a command you specify. 

VELP L Displays a listing of the last 60 keys you pressed. 

K£LP U Offers to "undo" the last major Zmacs operation, such as 

sorting or filling, when possible. 

HELP V Displays the names and values of Zmacs variables whose 

names contain a string you specify. 

hCLP U Displays the key binding for a command you specify. 

(U refers to "where".) 

HELP SPACE Repeats the last HELP command. 



2.1.2 Completion 

Some Zmacs operations require you to provide names — for example, names 
of extended commands. Lisp objects, buffers, or Hies. You usually supply 
names by typing characters into a minibuffer that appears near the bottom 
of the screen. Often you do not have to type all the characters of a name; 
Zmacs offers completion over some name spaces. When completion is 
available, the word "Completion" appears in parentheses above the right side 
of the minibuffer. 

You can request completion when you have typed enough characters to 
specify a unique word or name. For extended commands and most other 
names, completion works on initial substrings of each word. For example, 
n-X c b is sufficient to specify the extended command Compile Buffer. 
SPfK^E, COrPLETE, RETURN, and END complete names in different ways. 
VELP and [Zmixs Window (R)] list possible completions for the characters 
you have typed. 

Reference 

SPfK£ Completes words up to the current 

word. 

HELP or C-? Displays possible completions in the 

typeout area. 

[Zmacs Window (R)] Pops up a menu of possible 

completions. 

COMPLETE Displays the full name if possible. 

RETURN or END Confirms the name if possible, 

whether or not you have seen the full 
name. 
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2.2 Getting Started 

When Symbolics programmers begin to write new Lisp programs, they often follow these steps: 

1. Enter the Zmacs editor. 

2. Create a buffer for a new file for the program. 

3. Set the attributes of the buffer and file, including major and minor modes. 



2.2.1 Entering Zmacs 

Use SELECT E or [Edit] from a system menu to enter Zmacs. 

Reference 

SELECT E Selects a Zmacs frame. 

[Edit] (from a system menu) Selects a Zmacs frame. 



2.2.2 Creating a File 

To store program code in a new file, use Find File (c-X c-F) to create a 
buffer for the file at the beginning of the editing s«sion. You can then 
edit the file's attributes or create an attribute list that appears in the text 
(see section 2.2.3, page 7). You will not have to interrupt later work to 
name the file or check its attributes before you save it. 

Reference 

Find File (c-X c-F) Creates and names a buffer for the 

nie, reading in the file if it already 
exists. 



2.2.3 File Attribute Lists 

Each buffer and generic pathname has attributes, such as Package and Base, 
which can also be displayed in the text of the buffer or file as an attribute 
list. An attribute list must be the Hrst nonblank line of a Hie, and it must 
set off the Hsting of attributes on each side with the characters "-•-". If 
timeline appears in a file, the attributes it specific are bound to the values 
in the attribute list when you read or load the file. 

Suppose you want the new program to be part of a package named 
graphics that contains graphics programs. In this case, you want to set the 
Package attribute to graphics in three places: the generic pathname's 
property list; the buffer data structure; and the buffer text You can make 
the change in two ways: 

• If the package ah-eady existe in your Lisp environment, use Set Package 
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(m-X) to set the package for the buffer. The command asks you whether or 
not to set the package for the fUe and attribute list as well. You cannot 
use this conmiand to create a new package. 

Use Update Attribute List (m-X) to transfer the current buffer attributes to 
the file and create a text attribute list. Edit the attribute list, changing the 
package. Use Reparse Attribute List (m-X) to transfer the attributes in the 
attribute list to the file and the buffer data structure. If the package you 
specify by editing the attribute list does not exist in your Lisp environment, 
Reparse Attribute List asks you whether or not to create it under global. 

When you specify a package by editing the attribute Ust, you can explicitly 
name the package's superpackage and, if you want, give an initial estimate 
of the number of symbols in the package. (If the number of symbols 
exceeds this estimate, the name space expands automatically.) Instead of 
typing the name of the package, type a representation of a list of the form 
{package superpackage svmbol-couni) . To indicate that the graphics 
package is inferior to global and might contain 1,000 symbols, type into the 
attribute list: 

Package: (GRAPHICS GLOBAL 1000) 

See the Lisp Machine Manual, section 21.9.2, page 369, and Release 4.0 
Release Notes, sections 5.3.S and 5.3.6, page 90; for more on fQe and buffer 
attributes. 

Example 

Suppose the package for the current buffer is nser and the base is 8. We 
want to create a package called graphics for the buffer and associated file. 
We also want to set the base to 10. If no attribute Ust exists, we use 
Update Attribute List (n-X) to create one using the attributes of the 
current buffer. An attribute Ust appears as the Hrst line of the buffer: 

;;; -*- Hode: LISP; Package: USER; Base: 8 -•- 

Now we edit the buffer attribute list to change the package specification 
from USER to (GRAPHICS GLOBAL 1000) and to change the base specification 
from 8 to 10. The text attribute list now appears as follows: 

;;; -«- Hode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -*- 

Finally, we use Reparse Attribute List (m-X). The package becomes 
graphics and the base 10 for the buffer and the file. 
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Reference 

Set attribute (m-X) 



Update Attribute List (m-X) 



Reparse Attribute List (ni-X) 



Sets attribute for the current buffer. 
Queries whether or not to set 
attribute for the file and in the text 
attribute list, attribute is one of the 
following: Backspace, Base, Fonts, 
Lowercase, NoHl^ Package, Patch 
File, Tab Width, or Vsp. 

Assigns attributes of the current 
buffer to the associated file and the 
text attribute list. 

Transfers attributes from the text 
attribute l^t to the buffer data 
structure and the associated file. 



2.2.4 Major and Minor Modes 

Each Zmacs buffer has a major mode that determines how Zmacs parses the 
buffer and how some commands operate. Lisp Mode is best suited to 
writing and editing Lisp code. In this major mode, Zmacs parses buffers so 
that commands to find, compile, and evaluate Lisp code can operate on 
definitions and other Lisp expre^ions. Other Zmacs commands, including 
LIKE, TRB, and conunent handlers, treat text according to Lisp syntax rules 
(see section 2.4, page 19). 

If you name a file with one of the types associated with the canonical type 
:lisp, its buffer automatically enters Lisp Mode. Following are some 
examples of names of files of canonical type :lisp: 



Host system 
Lisp Machine 
TOPS-20 
UNIX 



File name 

acme-blue : >syinbo1 1cs>examp1es>arrow. 1 1sp 
acme-20 :<symbo1 1cs.exainp1es>arrow. 1 1sp 
acme-vax: /symbol Ics/examples/arrow. 1 



You can also specify minor modes, including Electric Shift Lock Mode and 
Atom Word Mode, that affect alphabetic case and cursor movement. 
Whether or not you use these modes is a matter of personal preference. If 
you want Lisp Mode to include these minor modes by default, you can set a 
special variable in an init Hie. If you want to exit one of these modes, 
simply repeat the extended command. The command acts as a toggle switch 
for the mode. 



10 
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Example 

The following code in an init file makes Lisp Mode include Electric Shift 
Lock Mode if the buffer's Lowercase attribute is nil, as it is by default: 

(log In -forms 
(setq ziral: lisp-mode-hook 

»2we1:e1ectr1c-sh1ft-1ock-1f-appropr1ate)) 



Reference 

Lisp Mode (»-X) 



Electric Shift Lock Mode (m-X) 



Atom Word Mode (m-X) 



Auto Fill Mode (m-X) 



Set Fill Column (c-X F) 



Treats text as Lisp code in parsing 
buffers and executing some Zmacs 
commands. 

Places all text except comments and 
strings in upper case. 

Makes Zmacs word-manipulation 
commands (such as m-F) operate on 
Lisp symbol names. 

Automatically breaks lines that 
extend beyond a preset Hll colunm. 

Sets the fill column to be the column 
that represents the current cursor 
position. With a numeric argument 
less than 200, sets the fill coliunn to 
that many characters. With a larger 
nimieric argument, sets the Hll 
colunm to that many pixels. 



2.3 Program Development: Design and Figure Outline 



2.3.1 Program strategy 

Our goal in developing the sample program is to reproduce the pattern of 
striped arrows on the cover of this document. The pattern consists of one 
large arrow encl(»ing many small arrows that are similar to each other. 
Each arrow is a series of line segments that form either its outline or its 
stripes. 

We have two general problems in writing the program. We must calculate 
the position of each line segment we want to draw. We must also convert 
these positions into a form that will produce line segments on the output 
device we choose. 

In solving these problems, we want to adhere to two principles: 
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• We want the program to be as modular as possible. The routine that 
calculate line positions should not depend on the output device we cho(se. 
The routines that translate positions for the output device should not 
depend on any particular method of calculating thc^e positions. If we want 
to change the internal operation of either set of routines, we should not 
have to change the other. 

• We want to write the program in an incremental style. We write the 
program in stages, producing a working version at each stage. We start 
with simple tasks and gradually add refinements until we are satisfied with 
what the program accomplishes. 

We write the program in two modules, one to calculate line positions and 
the other to translate positions for the output streams. We put these 
modules in separate files: The first appears in appendix A (page 133), the 
second in appendix B (page 147). 

How do we send line positions from the module that calculates them to the 
module that transmits them to output? The output module, which we 
discuss in detail in chapter 5 (page 101), consists of definitions of flavors 
and methods to transfer information to the appropriate output stream. 
Streams for LGP and screen output can both produce lines using the 
coordinates of the endpoints. Our module that calculates line positions 
needs to compute the coordinates of the endpoints of the lines to be drawn. 
In the output module, we define a generic operation called :$how-lines to 
receive the coordinates from the calculation module and translate them for 
the appropriate output stream. The calculation module sends ^how-lines 
messages to the output module. We can decide at run time which ou^ut 
stream to use. 

Now that we have defined the interface between the two modules, we could 
in principle write either module firet. Although we want the position- 
calculating routines to be independent of the output device, we have to 
choose a coordinate system for the calculations. For ease of interpretation, 
we place the origin at bottom left. This is the convention that the system 
LGP routines use, but the origin for screen coordinates is at top left. For 
the sake of convenience, we calculate positions in units of LGP pixels. 



2.3.2 Simple Screen Output 

We discuss the output routines in chapter 5 (page 101). Eventually, we 
want to produce output on the screen, an LGP, or a file. To develop the 
program, we need a routine for simple screen display so that we can check 
the results of our calculation routines. We can use the stream that is the 
value of terminal-io. This stream handles :draw-line messages whose 
arguments include the coordinates of the endpoints of the lines to be drawn. 
(See Introduction to Using the Window System, section 2.4, page 30, for more 
on :draw-Iine.) 
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We first create a source file for the output routine. We define a flavor, 
screen-arrow-ootpat, and a method to handle :show-lines messages from 
the calculation routines. The arguments to rshow-lines are the coordinates 
of the endpoints of one or more lines to be drawn. If the message has more 
than four arguments — the coordinates of two endpoints — we assume that 
we are to draw more than one line, each starting at the endpoint of the last. 
The :show-lines method must iterate over the arguments of the message 
and send terminal-io a :draw-line message for each hne to be drawn. 

We must remember to transform the y-coordinate to take account of the 
screen's origin at the top. We must also scale both coordinates to take 
account of the LGP*s higher resolution: Screen pixels are about 2.5 times as 
large as LGP pixels. 

The following code provides this simple output module: 

(defflavor screen-arrow-output 
((scale-factor 2.5)) 
()) 

(defnethod (screen-arrow-output :show-11nes) 
(x y &rest x-y-pairs) 
(loop for xO s (send self *:coo«)ute-x x) then xl 
for yO s (send self *:c(Mq)ute-y y) then yl 
for (xl yl) on x-y-paIrs by #'cddr 
do (setq xl (send self *:cofl4>ute-x xl) 
yl (send self *:compute-y yl)) 
(send terminal -1o *: draw- line 

xO yO xl yl tv:a1u-1or t))) 

(defnethod (screen-arrow-output :conpute-x) (x) 
(fixr (// X scale-factor))) 

(defnethod (screen-arrow-output :compute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 



2.3.3 Outlining the Figure 

We now begin to write the module that calculates the coordinates of the 
lines that make up the figure. First we must decide how to represent the 
large arrow that encloses the figure and the smaller arrows inside it. As the 
diagram in appendix A (page 133) shows, seven points define each arrow. 
Each arrow has a head, bounded by points 0, 1, and 6, and a shaft, bounded 
by points 2, 3, 4, and 5. The large outer arrow and the smaller inner 
arrows differ in their shafts. Each inner arrow has two yet smaller arrows 
beneath it. The inferior arrows overlap the shafts of the superior arrows 
and turn each shaft into a series of dncending triangles. 

We have two kinds of arrow, represented by the large outer arrow and the 
small inner ones. We can treat these differences in several ways: 
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• We can deHne two structures, make each arrow an instance of one of the 
structures, and store information about each arrow in the structure's slots 
(see the Lisp Machine Manual, chapter 19, page 257). 

• We can define two flavors, make each arrow an instance of one of the 
flavors, and store information about each arrow in the flavor's instance 
variables (see the Lisp Machine Manual, chapter 20, page 279). 

• We can simply define global variables to represent the state of the current 
arrow. 

Whichever method we choose, some operations, such as striping the 
arrowheads, will be the same for both kinds of arrows. Other operations, 
such as striping the shafts, will depend on the kind of arrow we are 
drawing. 

For simplicity, we use global variables to hold information about the arrows, 
and we use functions to deHne procedures for calculating coordinates. Note 
that we bind the global variables rather than set them. We do this because 
we might eventually have two or more arrow programs running at the same 
time in separate processes. If we set global variables, one program might 
incorrectly use a value set by another (see section 5.1.6, page 117). 

Our Hrst task in writing the calculation module is to outline the arrows. 
After creating a file for the module, we write the code for this task in six 
steps: 

1. Define variables to hold information about the arrow we are drawing. For 
the :show-lines message we need the x- and y-coordinat^ of the seven 
points that define the arrow. We also need the length of the top edge of 
the arrow, which we use as a base length. In calculating coordinates, we 
also need the values of one-half and one-fourth the length of the top edge. 

We use def var to declare global variables near the beginning of the file (see 
the Lisp Machine Manual, section 3.1, page 14). This macro declares 
variables special for the compiler and lets us supply default initial values and 
documentation strings. By convention, we surround the names of global 
variables with asterisks to distinguish them from names of local variables. 



(defvar •top-edge* nil 
"Length of the top edge of the arrow") 

(defvar *top-edge-2* nil 
"Half the length of the top edge") 

(defvar •top-edge-4* nil 
"One-fourth the length of the top edge") 

(defvar "pOx* nil 

"X-coordlnate of point 0") 
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(defvar 'pOy* nil 
"Y-coordlnate of point 0") 

(defvar *plx« nil 
"X-coordlnate of point 1") 

(defvar •ply* nil 

"Y-coordlnate of point 1") 

(defvar 'pZx* nil 
"X-coordlnate of point 2") 

(defvar 'pZy* nil 
■Y-coordlnate of point 2") 

(defvar 'pSx* nil 
"X-coordlnate of point 3") 

(defvar "pSy* nil 
■Y-coordlnate of point 3^) 

(defvar •p4x* nil 

"X-coordlnate of point 4") 

(defvar •p4y« nil 
■Y-coordlnate of point 4") 

(defvar 'pSx* nil 
"X-coordlnate of point 5") 

(defvar "pSy* nil 

■Y-coordlnate of point 5') 

(defvar «p6x* nil 

■X-coordlnate of point 6") 

(defvar 'pey* nil 
■Y-coordlnate of point 6") 

2. Define an initial function, draw-arrow-graphic, for the calculation module. 
We will call this function from the one we invoke to start the program. We 
pass draw-arrow-graphtc the length of the top edge of the large arrow and 
the coordinates of its top right point (point 0). These arguments determine 
the position and size of the arrow. The function also calculates the half 
and quarter lengths of the top edge. 



(defun draw-arrow-graphic (*top-edge* 'pOx* •pOy*) 
(let ((•top-edge-2« (// nop-edge* 2)) 

(•top-edge-4» (// *top-edge* 4))))) 
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3. Outline the large arrow. We compute the coordinates of the other six 
points of the arrow, then send a rshow-lines message to draw the lines. We 
can calculate the coordinates of points 1, 2, 5, and 6 the same way for both 
the large and small arrows. We put these calculations in a separate function 
so that we can use the same code for both kinds of arrow. We need a 
constant to hold the destination of the :show-lines messages. We must add 
to draw-trrow-graphic a call to draw-big-arrow. 



(def const *dest* nil 

"Destination of :SHOW-LINES messages to output") 



(defun draw-arrow-graphic ('top-edge* 'pOx* 'pOy*) 
(let ((*top-edge-2« (// nop-edge* 2)) 
(•top-edge-4« (// *top-edge« 4))) 
(draw-big-arrow))) 



(defun draw-big-arrow () 
(multlple-value-blnd 

(*plx« 'ply* *p2x« «p2y* 'pSx* «p5y« «p6x« 'pey*) 

(compute-arrowhead-polnts) 
(multlple-value-blnd (»p3x* «p3y* •p4x« •p4y*) 
(coiiv>ute-arrow-shaft-po1nts) 
(draw-b1g-outl1ne)))) 

(defun compute-arrowhead-polnts () 
(let* ((plx (- *pOx* «top-edge*)) 
(ply *pOy*) 

(p2x (♦ plx *top-edge-4*)) 
(p2y (- 'pOy* *top-edge-4*)) 
(p6x *pOx*) 

(p6y (- *pOy* *top-edge*)) 
(p5x (- *pOx* *top-edge-4*)) 
(p5y (+ p6y *top-edge-4«))) 
(values plx ply p2x p2y p5x p5y p6x p6y))) 

(defun compute-arrow-shaft-points () 
(values (- *plx* *top-edge-4*) 
(- •p2y* *top-edge-2*) 
•p2x* 
(- *p2y* *top-edge*))) 

(defun draw-blg-outllne () 
(send *dest* *: show- lines 

*pOx* *pOy* *plx* *ply* *p2x* *p2y* *p3x* *p3y* 
*p4x* *p4y* 'pSx* *p5y* *p6x* *p6y* *pOx* *pOy*)) 



4. Outline the largest of the small arrowheads. We can generate all the 
interior outlines in the figure by outlining only the heads of the small 
arrows. We first draw the largest of these arrowheads by analogy with our 
drawing the large arrow. We can use our function 
compate-arrowhead-points to calculate the coordinates of the vertexes. 
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First we need to halve the value of *top-edge« and bind new values for the 
coordinates of the top right point of the arrow. 



(defun draw-arrow-graphic (*top-edge* *pOx* *pOy*) 
(let ((*top-edge-2« (// nop-edge* 2)) 
(*top-edge-4« (// •top-edge* 4))) 
(draw-big-arrow) 
(let ((«top-edge* nop-edge-Z*) 

(«pOx« (- 'pOx* *top-edge-2*)) 
(«pOy« (- tpOy* *top-edge-2*))) 
(do-arrows)))) 

(defun do-arrows () 
(let ((•top-edge-2* (// nop-edge* 2)) 
(*top-edge-4* (// *top-edge« 4))) 
(draw-arrow))) 

(defun draw-arrow () 
(multlple-value-blnd 

(•plx* 'ply* •p2x* *p2y» 'pSx* 'pSy* "pex* 'pey*) 

(coii4>ute-arrowhead-po1nts) 
(draw-outline))) 

(defun draw-outline () 
(send "dest* *:show-11nes *p2x* «p2y* "plx* 'ply* 
•pOx* 'pOy* 'pex* 'pey* 'pSx* 'pSy*)) 



S. Outline the rest of the small arrows. Each small arrow has two inferior 
arrows beneath it. We modify our function do-arrows by adding two 
recursive function calls: one to draw the left-hand inferior of each superior 
arrow, and one to draw the right-hand inferior. We limit the levels of 
recursion by deHning a constant, *Biax-depth*, and incrementing the 
variable *depth* on each call to do-arrows until *depth* equals 
*Bax-depth*. 



(defvar *depth* 
"Level of recursion for the current arrow") 

(def const *max-depth* 7 
"Number of levels of recursion") 

(defun draw-arrow-graphic (*top-edge* 'pOx* *pOy*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(•top-edge-4* (// nop-edge* 4))) 
(draw-big-arrow) 
(let ((*top-edge* *top-edge-2*) 

(*pOx* (- *pOx* * top-edge-2*)) 
(*pOy* (- «pOy* *top-edge-2*)) 
(*depth* 0)) 
(do-arrows)))) 
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(defun do-arrows () 
(Mhen (< *depth* •max -depth*} 
(let ({•top-edge-2* (// *top-edge* 2)) 
(•top-edge-4« (// «top-edge« 4))) 
(draw-arrow) 
(let (('depth* (1+ *depth«)) 

(*top-edge* *top-edge-2») 

(•pOx* (♦ *top-edge-4* (- 'pOx* nop-edge*))) 
(«pOy« (- *pOy* •top-edge-4«))) 
(do-arrows)) 
(let (('depth* (1+ 'depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (- *pOx* *top-edge-4*)) 
(*pOy* (♦ *top-edge-4* (- *pOy* *top-edge*)))) 
(do-arrows))))) 



6. Define a function we can call to produce the graphic. This function has to 
make an instance of screen-arrow-oatpnt, clear the screen, and call 
draw-arrow-graphic. The arguments to draw-arrow-graphic determine 
the size and placement of the figure. For now, we use estimates based on 
the dimensions, in pixels, of an LGP page. 



(defun do-arrow () 
(let ((*dest* (make- Instance *screen-arrow-output))) 
(send termlnal-lo 'rclear-screen) 
(draw-arrow-graphic 1280 1800 1800))) 



We now have a simple working version of our program. We first compile 
our code (see section 3.1, page 62). We then use SELECT L to select a Lisp 
Listener. There we can evaluate (graphics: do-arrow) to nm the program. 
We can avoid typing the package prefix by first using pkg-goto to make the 
current package graphics: 

(pkg-goto * graphics) 



When we run the program, we generate a screen image of the arrow 
outlines. Figiu-e 1 (page 18) shows the output of the program at this stage. 

These six steps illustrate a pattern of incremental program development 

• We make each function initially simple. We add new functions and edit old 
ones as tasks become more complex or refined. Facilities for keeping track 
of Lisp syntax (section 2.4, page 19) and for editing code (section 2.8, 
page 49) encourage this incremental style. 

• We compile, t^t, and debug code in sections as we write it Many 
Symbolics programmers, for example, would test draw-arrow both before 
and after adding the recursive function caUs. 
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Figure 1. Program output with only the outlines of the arrows in the 
figure. 
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To support this incremental style, we must be able to check the syntax of 
our code, edit it, and compile it in sections. We discuss facilities for 
keeping track of Lisp syntax in the next section; techniques for editing code 
in section 2.8 (page 49); and methods of compiling and evaluating in 
chapter 3 (page 61). 

2.4 Keeping Track of Lisp Syntax 

Zma<» allows you to move easily through Lisp code and format it in a readable style. 
Commands for aligning code and features for checking for unbalanced parentheses can help you 
detect simple syntax errors before compiling. 

Zmacs facilities for moving through Lisp code are typically single-keystroke commands with 
c-m- modifiers. For example. Forward Sexp (c-m-F) moves forward to the end of a Lisp 
expression; End Of Definition (c-m-E) moves forward to the end of a top-level definition. 
Most of these commands take arguments specifying the number of Lisp expressions to be 
manipulated. In Atom Word Mode word-manipulating commands operate on Lisp symbol 
names; when executed before a name with hyphens, for example. Forward Word (m-F) places 
the cursor at the end of the name rather than before the first hyphen (see section 2.2.4, 
page 9). 

See the Lisp Machine Summary for a list of common Zmacs commands for operating on Lisp 
expressions. 

2.4.1 Comments 

You can document code in two ways: You can supply documentation 
strings for functions, variables, and constants (see section 2.6, page 28); and 
you can insert conmients in the source code. You can retrieve 
documentation strings with Zmacs commands and Lisp functions 
(section 2.6, page 28). The Lisp reader ignores source-code comments. 
Although you cannot retrieve them in the same ways as documentation 
strings, they are essential to maintaining progranu and useful in testing and 
debugging (see chapter 3, page 61, and chapter 4, page 71). 

Most source-code comments begin with one or more semicolons. Symbolics 
programmers follow conventions for aligning comments and determining the 
number of semicolons that begin them: 

• Top-level comments, starting at the left margin, begin with three semicolons. 

• Long comments about code within Lisp expressions begin with two 
semicolons and have the same indentation as the code to which they refer. 

• Comments at the ends of lines of axle start in a preset column and begin 
with one semicolon. 

You can also use #| to begin a comment and |# to end one. The comment 
can extend for more than one line. You can nest #| and |# within longer 
comments. 
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Example 

Let's add some comments to draw-arrow-graphic. We can write a top- 
level comment without regard for line breaks and then use Fill Long 
Comment (m-X) to fill it. We use c-j to insert a comment on the current 
line. We use m-LINE to continue a long comment on the next line. 

This function controls the calculation of the coordinates of the 
endpolnts of the lines that make up the figure. The three arguments 
are the length of the top edge and the coordinates of the top right 
point of the large arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW 
to draw the large arrow and then calls DO-ARROWS to draw the smaller 
ones. 

(defun draw-arrow-graphic (*top-edge* 'pOx* •pOy«) 
(let ((*top-edge-2* (// «top-edge* 2)) 
(«top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) ;Draw large arrow 

;; Length of the top-edge for the first small arrow Is half the 
;; length for the large arrow. Bind new coordinates for the top 
;; right point of the small arrow, 
(let ((*top-edge* nop-edge-Z*) 

(•pOx* (- 'pOx* *top-edge-2*)) 
(•pOy* (- •pOy« nop-edge-Z*)) 
(•depth* 0)) 
(do-arrows)))) ;Draw small arrows 



Reference 

Indent For Comment (c-; or »-; ) 



Kill Comment (c-«-i ) 
Down Comment Line (i»-N) 

Up Comment Line (»-P) 



Inserts or aligns a comment on the 
current Une, beginning in the preset 
comment column. 

Removes a comment from the current 
line. 

Moves to the comment column on the 
next line. Starts a comment if none 
is there. 

Moves to the comment column on the 
previous line. Starts a comment if 
none is there. 



Indent New Comment Line («-LINE) When executed within a comment, 

inserts a newline and starts a 
comment on the next line with the 
same indentation as the previous line. 



Fill Long Comment (m-X) 



When executed within a comment 
that begins at the left margin, fills the 
comment. 
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Set Comment Colimm (c-X ; ) 



Sets the column in which comments 
begin to be the colimm that 
represents the current cursor position. 
With an argimient, sets the conunent 
column to die position of the previous 
comment and then creates or aligns a 
comment on the current line. 



2.4.2 Aligning Code 

Code that you write sequentially will remain properly aligned if you 
consistently press LIN£ (instead of RETIA^N) to add new lines. When you 
edit code, you might need to realign it c-m-Q and c-m-s are useful for 
aligning definitions and other Lisp expressions. 



Reference 

Indent New Line (LINE) 



Indent For Lisp (TfiB or c-m-TFIB) 

Indent Sexp (c-m-Q) 
Indent Region (c-i»-n) 



Adds a newline and indents as 
appropriate for the current level of 
Lisp structure. 

Aligns the current line. If the line is 
blank, indents as appropriate for the 
current level of Lisp structure. 

Aligns the Lisp expression following 
the cursor. 

Aligns the current region. 



2.4.3 Balancing Parentheses 

When the cursor is to the right of a close parenthesis, Zmacs flashes the 
corresponding open parenthesis. The flashing open parentheses, along with 
proper indentation, can indicate whether or not parentheses are balanced. 
Improperly aligned code (after you use a c-n-Q command, for instance) is 
often a sign of unbalanced parentheses. 

To check for unbalanced parenth^es in an entire buffer, use Find 
Unbalanced Parentheses (nt-X). Zmacs can check source files for 
unbalanced parentheses when you save the flies. If a flle contains 
unbalanced parentheses, Zmacs can notify you and ask whether or not to 
save the flle anyway. To put this feature into effect, place the following 
code in an init flle: 



(logln-forns 
(setq zwe1:*check-unba1ancecl-parentheses-when-sav1ng* t)) 
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Reference 

Find Unbalanced Parentheses (m-X) 



Searches the buffer for unbalanced 
parentheses. Ignores parentheses in 
comments and strings. 



2.5 Program Development: Drawing Stripes 

So far the sample program outlines all the arrows in the figure. The next task is to draw the 
diagonal stripes. To keep this stage as simple as possible, we ignore the differences in spacing 
and thickness of lines in the figure. We draw each stripe from upper left to lower right. We 
draw the stripes in five steps: 

1. Determine the distance between stripes. We first define a constant, 
*do-the-strlpes*, that we bind to t when we want to draw stripes and nil 
when we want only outlines. We deHne another constant, 
*stripe-distance*, to contain the horizontal distance between stripes. Let* s 
assume we want 64 stripes in the large arrowhead. We divide the initial 
*top-edge* by 64 to obtain *strlpe-distance*. 



(def const «do-the-stripes« t 
•When t, permits striping of the figure") 

(defconst *str1pe-d1stance* nil 
"Horizontal distance between stripes In the large arrow") 

(defun draw-arrow-graphic (nop-edge* *pOx« *pOy«) 
(let ((•top-edge-2* (// nop-edge* 2)) 
(•top-edge-4* (// nop-edge* 4)) 

;; Compute horizontal distance between stripes In the 
;; large arrow, assuming 64 stripes In the large 
;; arrowhead. 

(•str1pe-d1stance« (// "top-edge* 64))) 
(draw-big-arrow) ;Draw large arrow 

;; Length of the top-edge for the first small arrow Is half the 
;; length for the large arrow. Bind new coordinates for the top 
;; right point of the small arrow, 
(let ((*top-edge* *top-edge-2*) 

(•pOx* (- *pOx* *top-edge-2*)) 
(«pOy« (- *pOy* *top-edge-2*)) 
(*depth* 0)) 
(do-arrows)))) ;Draw small arrows 



2. Stripe the head of the large arrow. We define a function, 
stripe-arrowhead, and call it from draw-big-arrow. The function loops to 
calculate the coordinates of the endpoints of the stripes, starting in the 
upper right corner and decrementing x and y by •stripe-distance*. 
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(defun draw-big-arrow () 

;; Deternlne coordinates of arrowhead vertexes 
(RNiltlple-value-blnd 

(•plx* 'ply* «p2x* •p2y« 'pSx* *p5y« 'pex* «p6y*) 

( compu te-arrowhead-pol nts ) 
;; Deternlne coordinates of shaft vertexes 
(multlple-value-blnd (*p3x« 'pSy* •pAx* •p4y*) 
( compute-arrow-shaf t-pol nts ) 
(draw-blg-outllne) ;0ut11ne arrow 

(when *do-the-str1pes* 
(stripe-arrowhead)}))) ;Str1pe head 



; Function to control striping the head of each arrow. 
Determines coordinates of starting and ending points for each 
stripe. Calls DRAW-ARROWHEAD-LINES to draw each stripe, 
(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *pOx* 'top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from 'pOx* by *str1pe-d1stance* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom *pOy« by *str1pe-d1stance* 

;; Draw a stripe 

do (draw-arrowhead- lines start-x end-y))) 



Draws a stripe In an arrowhead. Arguments are the x-coord 
of the starting point and the y-coord of the ending point 
of a stripe, 
(defun draw-arrowhead- lines (start-x end-y) 
(send 'dest* *:show-11nes start-x «pOy* 'pOx* end-y)) 



3. Stripe the exposed portions of the shaft of the large arrow. The shaft 
consists of a series of descending triangles along the left and right sides. 
We define a function, stripe-big-arrow-shaft, to control the striping. We 
then define six functions, three to stripe the left side and three to stripe the 
right. The first function for each side iterates through the triangles that 
make up the shaft. The second function stripes one triangle. The third 
function draws one stripe. 
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(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multlple-value-blnd 

(•plx* *ply* *p2x« 'pZy* "pSx* *p5y« 'pOx* *p6y«) 

( compu te-arrowhead-po 1 nt s ) 
;; Determine coordinates of shaft vertexes 
(rouUlple-value-bInd (*p3x« "pSy* *p4x« •p4y*) 
(cmnpute-arrow-shaft-polnts) 
(draw-blg-outllne) ;0ut11ne arrow 

(when "do-the-strlpes* 

(stripe-arrowhead) ;Stripe head 

(stripe-big-arrow-shaft))))) ;Str1pe shaft 

Function to control striping the shaft of the large arrow. 
Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side, 
(defun stripe-big-arrow-shaft () 

(stripe-big-arrow-shaft-left) 

(str1pe-b1g-arrow-shaft-right)) 



Function to control striping left side of big arrow's shaft. 
Iterates over the triangles that make up the shaft. Determines 
coordinates of the apex and bottcm right point of each triangle. 
Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle, 
(defun stripe-big-arrow-shaft-left () 

;; Set up a counter for depth. Don*t exceed maximum recursion 
;; level. 

(loop for shaft-depth from below «max-depth* 
;; Find current top edge and its fractions 
for top-edge - *top-edge« then (// top-edge 2) 
for top-edge-2 ■ (// top-edge 2) 
for top-edge-4 * (// top-edge 4) 
;; Find coordinates of apex of triangle 
for apex-x = •p2x« then (- apex-x top-edge-2) 
for apex-y « •p2y« then (- apex-y top-edge-2) 
;; Find x-coord of bottom right vertex 
for right-x = (♦ apex-x top-edge-4) 
;; Find y-coord of bottom edge of triangle 
for bott(wi-y « (- apex-y top-edge-4) 
;; Stripe each triangle 
do (draw-big-arrow-shaft-stripes-left 

top-edge-4 apex-x apex-y right-x bottom-y))) 
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Stripes each triangle In left side of big arrow's shaft. 
Arguments are one-fourth current top edge, x- and y-coords 
of apex of triangle, x- and y-coords of bottom right vertex. 
Determines coordinates of starting and ending points for 
each stripe. Calls DRAW-BIG-ARROW-SHAFT-LINES-LEFT to 
draw the lines that make up each stripe, 
(defun draw-blg-arrow-shaft-strlpes-Teft 

(top-edge-4 apex-x apex-y right-x bottom-y) 
(loop with half-distance s (// *str1pe-d1stance* 2) 
;; Find x-coord of last stripe In triangle 
with last-x a (- apex-x top-edge-4) 

Find x-coord of top of each stripe, decrementing 
from the apex by HALF the horizontal distance 
between stripes. Stop at last stripe, 
for start-x from apex-x by half-distance above last-x 
;; Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
;; Find x-coord of endpoint of stripe 
for end-x downfrom rIght-x by *str1pe-d1 stance* 
;; Draw a stripe 

do (draw-blg-arrow-shaft-llnes-left 
start-x start-y end-x bottom-y))) 



Draws a stripe on the left side of the big arrow's shaft. 
Arguments are the coordinates of the starting and ending 
points of each stripe, 
(defun draw-big-arrow-shaft- lines- left 
(start-x start-y end-x end-y) 
(send *dest* ': show- lines 

start-x start-y end-x end-y)) 



;;; Function to control striping right side of big arrow's shaft. 
;;; Iterates over the triangles that make up the shaft. Determines 
;;; coordinates of the top point of each triangle. Calls 
;;; DRAW-BI6-ARR0W-SHAFT-STRIPES-RIGHT to stripe each triangle, 
(defun strlpe-blg-arrow-shaft-rlght () 

;; Set up a counter for depth. Don't exceed maximum recursion 
;; level. 

(loop for shaft-depth from below •max-depth* 
;; Find new top edge and Its fractions 
for top-edge « 'top-edge* then (// top-edge 2) 
for top-edge-2 * (// top-edge 2) 
for top-edge-4 * (// top-edge 4) 
;; Find coords of top point of triangle 
for start-x s (♦ *p2x* top-edge-4) 
for top-y « (- *p2y* *top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
;; Stripe the triangle 
do (draw-blg-arrow-shaft-strlpes-rlght 

top-edge-2 top-edge-4 start-x top-y))) 
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Stripes each triangle In right side of big arrow^s shaft. 
Arguments are one-half and one-fourth of current top edge, and 
coords of top point of the triangle. Determines coordinates of 
starting and ending points for each stripe. Calls 
DRAW-BIG-ARROW-SHAFT-LINES-RIGHT to draw a stripe, 
(defun draw-blg-arrow-shaft-strlpes-rlght 

(top-edg6-2 top-edge-4 start-x top-y) 
(loop with half -distance = (// 'stripe-distance* 2) 
;; Find y-coord of last stripe In triangle 
with last-y « (- top-y top-edge-2) 
;; Find y-coord of starting point of stripe. Don*t go 
;; past the end of the triangle. 

for start-y fr<»» top-y by «str1pe-d1stance* above last-y 
;; Find coords of ending point of the stripe, decrementing 
;; by HALF the horizontal distance between stripes 
for end-x downfrom (♦ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
;; Draw a stripe 

do (draw-blg-arrow-shaft-llnes-rlght 
start-x start-y end-x end-y))) 



Draws a stripe on the right side of the big arrow's shaft. 
; Arguments are the coordinates of the starting and ending points 
: of the stripe, 
(defun draw-blg-arrow-shaft-llnes-rlght 
(start-x start-y end-x end-y) 
(send *dest* *: show- lines 

start-x start-y end-x end-y)) 



4. Stripe the heads of the small arrows. We call stripe-arrowhead from 
draw-arrow. 



(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(multlple-value-blnd 
(•plx* «ply» •p2x« •p2y« 'pSx* *p5y* *p6x» *p6y«) 

(compute-arrowhead-points) 
(draw-outline) ;0utl1ne arrowhead 

(when «do-the-str1pes« 

(stripe-arrowhead)))) ;Str1pe head 



Stripe the exposed shafts of the small arrows. Like the shaft of the large 
arrow, these shafts are composed of a series of descending triangles. We 
define three functions: stripe-arrow-shaft iterates through the triangles 
that make up a shaft; draw-arrow-shaft-stripes stripes one triangle; and 
draw-arrow-shaft-lines draws one stripe. We call stripe-arrow-shaft from 
draw-arrow. 
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(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(nultlple-value-blnd 
(•plx« 'ply* 'pZx* 'pZy* 'pSx* «p5y* «p6x 

( compute-arrowhead-pol nts ) 
(draw-outline) 
(when *do-the-str1pes* 
(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft)))) ;Str1pe shaft 



•p6y«) 



;0ut11ne arrowhead 



Function to control striping the shaft of a small arrow. 
Iterates over the descending triangles that make up the shaft. 
Calculates the coordinates of the top left and bottom right 
vertexes of each triangle. Calls DRAW-ARROW-SHAFT-STRIPES to 
stripe each triangle, 
(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Oon*t exceed maxlnwrn 
;; recursion level. 

(loop for shaft-depth from *depth* below *max-depth* 
;; Calculate fractions of new top edge 
for top-edge-2 s *top-edge-2« then (// top-edge-2 2) 
for top-edge-4 = (// top-edge-2 2) 
;; Find coords of top left point of triangle 
for left-x s •p2x* then (- left-x top-edge-4) 
for top-y s •p2y* then (- top-y top-edge-2 top-edge-4) 
;; Find coords of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottoffl-y = (- top-y top-edge-2) 
;; Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y rIght-x botton-y))) 



: Stripes each triangle In the shaft of a small arrow. 
; Arguments are coordinates of the top left and bottom 
: right points of the triangle. Calculates the y-coord 
: of the starting point and the x-coord of the ending point 
of each stripe. Calls DRAW- ARROW-SHAFT- LINES to draw the 
stripe, 
(defun draw-arrow-shaft-stripes 

(left-x top-y rIght-x bott(MR-y) 
;; Find y-coord of starting point of stripe. Don't go 
;; below the bottom of the triangle. 

(loop for start-y from top-y by *str1pe-d1stance* above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x downfrom rIght-x by *str1pe-d1 stance* 
;; Draw a stripe 
do (draw-arrow-shaft- lines 

left-x start-y end-x bottom-y))) 
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;;; Draws a stripe In the shaft of a small arrow. Arguments are 
;;; the coordinates of the starting and ending points of the 
;;; stripe, 
(defun draw-arrow-shaft- lines 

(left-x start-y end-x bottom-y) 
(send *dest* *:show-11nes 

left-x start-y end-x bottom-y)) 

Figure 2 (page 29) shows the output of the program, with stripes of even spacing and thickness. 
This stage in program development differs from the beginning of the program in two ways: 

• As we add new functions, we need to refer to existing code for such 
information as the order of arguments in argument lists and the values of 
variables and constants (section 2.6, page 28). 

• We must start to change existing code, adding function calls and new 
arguments. These changes require increasing use of facilities for editing 
code (section 2.8, page 49). 

2.6 Finding Out About Existing Code 

When you write or edit programs, you often need to find characteristics of existing code. If 
you write programs incrementally, you need to Hnd existing deHnitions, argument lists, and 
values. To maintain modularity, you must know how new code should interact with previously 
written modules. If you want to incorporate parts of the Lisp Machine system in your 
programs, you often have to refer to system source code. 

Zmacs and Zetalisp have many facilities for retrieving information about Lisp objects and for 
displaying and editing source code. This section describes features specially useful for writing 
and editing code. We discuss facilities for learning about Lisp objects, symbols, variables, 
functions, and pathnames. 

2.6.1 Objects 

describe displays information about a Lisp object in a form that depends 
on the object's type. For example, for a special variable, describe displays 
the value, package, and properties, including documentation, pathname of 
the source file, and Zmacs buffer sectioning node. 

An interactive, window-oriented version of describe is the Inspector (see 
section 4.7, page 94). 

describe does not display array elements. For that you can use the 
Inspector or listarray. 

Example 

(describe * 'top-edge*) 
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Figure 2. Program output with stripes of even spacing and density. 
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The value of *T0P-ED6E* Is NIL 
•TOP-EDGE* Is In the GRAPHICS package. 
•TOP-EDGE* has property DOCUMENTATION: 

"Length of the top edge of the arrow" 
*TOP-EDGE* has property SPECIAL: 

#<UNIX-PATHNAME "VIXEN: //dess//doc//workstyles//pcodex.»"> 
#<UNIX-PATHNAHE "VIXEN: //dess//doc//worksty1es//pcodex.«">, 

an object of flavor FS: UNIX- PATHNAME. 

has Instance variable values: 

FS:HOST: #<UNIX-CHAOS-HOST SCRC-VIXEN> 

FS:DEVICE: :UNSPECIFIC 

FS:DIRECTORY: ("dess" "doc" "workstyles") 

FS:NAME: "pcodex" 

FS:TYPE: NIL 

FS: VERSION: :UNSPECIFIC 

SI: PROPERTY-LIST: (BASE 10 :MODE ...) 

FS:STRING-FOR-PRINTING: "VIXEN: //dess//doc//worksty1es//pcodex.*' 

FS:STRING-FOR-HOST: "//dess//doc//workstyles//pcodex.«" 

FS:STRING-FOR-EDITOR: NIL 

FS:STRING-FOR-DIRED: NIL 

FS:STRING-FOR-DIRECTORY: NIL 

*TOP-EDGE* has property SOURCE-FILE-NAME: 
((DEFVAR #<UNIX-PATHNAME 

"VIXEN: //dess//doc//workstyles//pcodex.«">)) 
((DEFVAR #<UNIX-PATHNAME 

"VIXEN: //dess//doc//worksty1es//pcodex.«">)) Is a list 

•TOP-EDGE* has property ZWE I :ZMACS- BUFFERS: 

((DEFVAR #<SECTION-NOOE Variable 'TOP-EDGE* 27316607») 

((DEFVAR #<SECTION-NODE Variable *T0P-ED6E* 27316607») Is a list 

*TOP-EDGE* 



Reference 

(describe object) Displays information about object in a 

fonn that depends on the object's 
type. For named structures, displays 
the symbolic names and contents of 
the entries in the structure. 

(listarray array) Returns a list whose elements are the 

elements of arrqf. 



2.6.2 Symbols 

Several Zmacs commands and Lisp functions find the name of a symbol or 
retrieve information about it. Unless you specify a package, most of these 
commands search the global package and its inferiors. It now takes several 
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minutes to search all these packages; if you don't know which one the 
symbol is in, you might want to use functions like apropos and who-calls 
only as a last resort. (See Program Development Help Fadlities for more on 
the meanings and default values of argument to th«« functions.) 



Example 

In defining the function stripe-big-arrow-shaft-left, we need to use the 
constant ^max-depth*, but we remember only that its name contains 
"depth". We use either m-ESCflPE (to evaluate a form in the editor 
minibuffer) or SELECT L (to select a Lisp Listener) and then evaluate: 

(apropos "depth" * graphics) 

GRAPHICS: DEPTH 

GRAPHICS: •MAX-DEPTH* - Bound 

GRAPHICS :SHAFT-DEPTH 

GRAPHICS :*DEPTH* - Bound 

(•DEPTH* SHAFT-DEPTH *HAX-DEPTH* DEPTH) 



Example 

After compiling stripe-arrowhead we want to test the program as written 

so far, but we forget which function calls draw-arrow-graphic: 

(who-calls * draw-arrow-graph 1c * graphics) 

DO-ARROW calls DRAW-ARROW-GRAPHIC as a function. 
(DO-ARROW) 

You can also find the callers of a function with List CMers (m-X) (see 
section 2.6.4, page 33). 



Reference 

(apropos string package inferiors superiors^ 

Displays the names of all symbols 
whose names contain string. Indicates 
whether or not the symbol is bound. 
Displays argument lists of functions. 

Where Is Symbol (m-X) Displays the names of packages that 

contain the specified symbol. 

(where-is string packaeii Displays the names of packages that 

contain a symbol whose print name is 
string. 

(who-calls symbol pockaee inferiors superiors^ 

Displays information about uses of 
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(what-f iles-call symbol vackae^ 



(plist symbotj 



List Matching Symbok (m-X) 



symbol as function, variable, or 
constant. Returns a list of the names 
of callers of symM. 

Displays names of files that contain 
uses of symbol as function, variable, 
or constant. 

Returns the list representing the 
property list of symbol. 

Displays the names of symbols for 
which a predicate lambda-expression 
returns something other than nil. 
Prompts for a predicate for the 
expression (lambda (symbol) 
predicate). By default, searches the 
current package; with an argument of 
c-U, searches all packages; with an 
argument of c-U c-U, prompts for 
the name of a package. Press c-. to 
edit definitions of symbols that satisfy 
the predicate. 



2.6.3 Variables 



Describe Variable At Point (c-sh-V) is a useful command to display 
information about a variable. It tells you whether or not the variable is 
bound, whether it has been declared special, and the file, if any, that 
contains the declaration. You can find the value of a variable by evaluating 
it in a Lisp Listener. If you have added a documentation string to the 
variable declaration, you can retrieve the string with c-sh-V or with 
c-sh-D, la-sh-D, or docamentation (see section 2.6.4, page 33). 



Example 

In writing stripe-arrow-shaft we want to find out whether or not 

*max-depth* is bound. c-sh-V displays the following information: 

•HAX-DEPTH* has a value and Is declared special by file 
VIXEN: /dess/doc/workstyles/pcodex. 1 
Number of levels of recursion 



Reference 

Describe Variable At Point (c-sh-V) Indicates whether or not the variable 

is declared special, is bound, or is 
documented by defvar or defconst. 
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2.6.4 Functions 

Many Zmacs and Zetalisp facilities for finding out about functions apply 
both to functions defined by defon and to objects defined by other special 
forms and macros that begin with "deP. 

2.6.4.1 Definitions 

Edit Definition («-. ) is a powerful command to find and edit definitions of 
functions and other objects. It is particularly valuable for finding source 
code, including system code, that is stored in a file other than that 
associated with the current buffer. It finds multiple definitions when, for 
example, a symbol is defined as a function, a variable, and a flavor. It 
maintains a list of these definitions in a support buffer, where you can use 
m-. to return to the definitions even when you are finished editing. 

Section 5.2.2 (page 129) describes how to use Edit Definition (m-. ) to edit 
definitions of flavor methods. 



Example 

We have written stripe-arrowhead and want to call it from 

draw-big-arrow. We use i»-. to position the cursor at the definition of 

draw-big-arrow. 



Reference 

Edit Definition (»-.) Selects a buffer containing a function 

definition, reading in the source file if 
necessary. You can specify a 
definition by typing the name into the 
minibuffer or clicking on a name 
already in the buffer. Offers name 
completion for definitions already in 
buffers. With a numeric argument, 
selects the next definition satisfying 
the most recently specified name. 

2.6.4.2 Names 

Often you know only part of a fimction name and need to find the 
complete name. Use Function Apropos (m-X). 



Example 

We want to call stripe-arrowhead from draw-arrow, but we remember 
only that draw-arrow contains the string "arrow". We use Function 
Apropos (»-X) to display the names of functions that contain "arrow". We 
click left on the name draw-arrow to edit its definition. 
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n-X Function Apropos arrow 

Functions matching arrow: 

DO-ARROW 

DO-ARROWS 

DRAW-ARROW 

DRAW-ARROW-GRAPHIC 

DRAW-ARROWHEAD-LINES 

DRAW-BIG-ARROW 

DRAW-BIG-ARROW-SHAFT-LIMES-LEFT 

DRAW-BIG-ARROW-SHAFT-LINES-RIGHT 

DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT 

DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT 

STRIPE-ARROWHEAD 

STRIPE-BIG-ARROW-SHAFT 

STRIPE-BIG-ARROW-SHAFT-LEFT 

STRIPE-BIG-ARROW-SHAFT-RIGHT 



Reference 

Function Aprop(» (m-X) Displays the nam^ of functions that 

contain a string. Press c-. or click 
left on names in the display to edit 
the definitions of the functions listed. 



2.6.4.3 Documentation 

Function definitions can include documentation strings. When you need to 
know the purpose of the function, you can retrieve the documentation with 
c-sh-D, n-sh-D, or docDmentation. 



Example 

We wrote a long source-code comment at the beginning of the definition of 
draw-arrow-graphic. We could have made this comment a documentation 
string: 
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(defun draw-arrow-graphic («top-Gdge« 'pOx* •pOy«) 

"Function controlling the calculation nodule. 
Controls calculation of the coordinates of the endpolnts of the lines 
that make up the figure. The three arguments are the length of the top 
edge and the coordinates of the top right point of the large arrow. 
DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow and then 
calls DO- ARROWS to draw the smaller ones." 
(let ((nop-edge-Z* (// «top-edge« 2)) 
(*top-edge-4* (// «top-edge« 4)) 
; Compute horizontal distance between stripes In the 
; large arrow, assuming 64 stripes In the large 
arrowhead, 
(•stripe-distance* (// 'top-edge* 64))) 
(draw-big-arrow) ;Draw large arrow 

; Length of the top-edge for the first small arrow Is half the 

length for the large arrow. Bind new coordinates for the top 
; right point of the small arrow, 
(let ((*top-edge* *top-edge-2*) 

(*pOx* (- *pOx* *top-edge-2*)) 
(«pOy* (- *pOy* *top-edge-2*)) 
(*depth* 0)) 
(do-arrows)))) ; Or aw small arrows 

Later, when defining do-arrow, we add a call to draw-arrow-grtphic. We 
want to be sure that this is the control function for the calculation module. 
We position the cursor at the name draw-arrow-graphic inside the 
definition of do-arrow and use m-sh-D to display the documentation string 
for draw-arrow-graphic: 

DRAW- ARROW-GRAPHIC: (*TOP-EDGE* *POX* *POY*) 

Function controlling the calculation module. 

Controls calculation of the coordinates of the endpolnts of the lines 

that make up the figure. The three arguments are the length of the top 

edge and the coordinates of the top right point of the large arrow. 

DRAW-ARROW-GRAPHIC calls DRAW- BIG -ARROW to draw the large arrow and then 

calls DO-ARROWS to draw the smaller ones. 



c-^^D displays the first line of the documentation string: 
DRAW-ARR(Hf-GRAPHIC: Function controlling the calculation module. 

To ensure that c-sh-D displays meaningful information, make the first line 
of each documentation string a complete sentence that summarizes the 
function. 



Reference 

Brief Documentation (c-sh-D) Displays the first line of the 

function's documentation string. 
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Long Documentation (m-sh-D) Displays the function's documentation 

string. 

(documentation function) Displays the function's documentation 

string. 

2.6.4.4 Argument Lists 

Quick Arglist (c-sh-fl) and arglist retrieve the argument list for a 
function. What these facilities display depends on the nature of the 
function, whether or not it has been compiled, and what options the 
function includes; see the Lisp Machine Manual^ section 10.9, page 150, and 
Program Development Help Facilities for details. 

Example 

We are editing the definition of do-arrow to add a call to 
draw-arrow-graphic. We want to see the argument list for 
draw-arrow-graphic. We position the cursor at the name 
draw-arrow-graphic in the deHnition of do-arrow and use c-sh-fl: 

DRAW-ARROW-GRAPHIC: (*TOP-EDeE* •POX* *POY*) 



Reference 

Quick Arglist (c-sh-fl) Displays a representation of the 

argument list of the current function. 
With a numeric argument, you can 
type the name of the function into 
the minibuffer or click on a function 
name in the buffer. 

(arglist function) Displays a representation of the 

function's argument list. 

2.6.4.5 Callers 

When you change a function definition, you sometimes need to make 
complementary changes in the function's callers. Foiu* Zmacs commands 
find the callers of a function. These conunands, Uke who-calls, now take 
several minutes to search all packages for callers. (For the example 
program, we need to search only the graphics package.) By default, these 
conunands search the current package. With an argument of c-U, they 
search all packages. You can specify the packages to be searched by giving 
the commands an argument of c-U c-U. 

Example 

We decide to change the order of the arguments to draw-trrow-graphic. 

We want to be sure to change all the callers of draw-arrow-graphic to call 
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the function with arguments in the correct order. We use Edit Callers 
(m-X). 



Reference 

List Callers (m-X) 



Multiple List Callers (m-X) 



Edit Callers (m-X) 



Multiple Edit Callers (m-X) 



Lists functions that call the specified 
function. Press c-. to edit the 
definitions of the functions listed. 

Lists functions that call the speciHed 
functions. Continues prompting for 
function names imtil you press only 
RETURN. Press c-. to edit the 
definitions of the functions listed. 

Prepares for editing the definitions of 
functions that call the specified 
function. Press c-. to edit 
subsequent deHnitions. 

Prepares for editing the definitions of 
functions that call the specified 
functions. Continue prompting for 
function names until you press only 
RETURN. Press c-. to edit subsequent 
definitions. 



2.6.5 Pathnames 

Zma(» provides several ways of finding the name of a Hie. If you just need 
the name of a Hie and have some idea what directory it is in, you can use 
c-X c-D with an argument of c-U or View Directory (m-X) to display a 
directory. If you want to operate on files in a directory, you can use c-X D 
with an argument of c-U or Dired (m-X) to edit a directory. If you want 
to find a source file but don't know what directory it is in, you might 
remember the name of a fimction defined in the file. In that case, you 
might be able to use m-. to find the file. 

Example 

After editing the definitions in the calculation module, we want to find the 
output module to edit the definition of do-arrow. We forget the name of 
the file, but we remember the name of the directory. We can use c-U c-X 
c-D to display the directory. If we have interned do-arrow or read its file 
into a buffer, we can use m-. to find do-arrow directly. 



Reference 

Display Directory (c-X c-D) 



Displays the oirrent buffer's file's 
directory. With an argument of c-U, 
prompts for a directory to display. 
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View Directory (m-X) 
tr Dired (c-X D) 



Dired («-X) 



Lists a directory. 

Edits the current buffer's Hle's 
directory. With an argument of c-U, 
prompts for a directory to edit. 
Displays the Hies in the directory. 
You can use single-character 
commands to operate on the files. 

Edits a directory. Displays the files 
in the directory. You can use single- 
character conunands to operate on the 
files. 



2.7 Program Development: Refining St ripe Density and Spacing 

At this stage of development, the program outlines the arrows in the Hgure and nils them with 
stripes of uniform thickn^s and spacing. In the Hnished figure, stripe thickness or density 
increases from upper right to lower left within each arrow, and stripe spacing varies among the 
levels of the figure. We adjust the stripe spacing by replacing the constant distance between 
stripes by a variable. We correct the stripe density by drawing multiple adjacent lines for each 
stripe. 

We adjust the stripe spacing in three steps: 

1. Define a variable, *strlpe-d*, to represent the distance between stripes for 
each arrow. 



(defvar 'strlpe-d* nil 

"Horizontal distance between stripes for each arrow") 



Calculate the value of *stripe-d* for each arrow. For the large arrow, this 
is just *$tripe-di5tance*. For the small arrows, we need to c^ a new 
function, compote-stripe-d, from draw-arrow, compote-stripe-d calculates 
*stripe-d* as a fraction of *stripe-distance* that depends on the level of 
recursion. It ensures that *stripe-d* divides *top-edge* evenly and that 
*stripe-d* is never less than 3. 
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(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multlple-value-blnd 
(•plx* *ply* •p2x« 'pZy* "pSx* 'pSy* 'pex* «p6y«) 

( compute-arrowhead-pol n ts ) 
;; Determine coordinates of shaft vertexes 
(multlple-value-blnd («p3x* «p3y* •p4x* •p4y*) 
(compute-arrow- shaft-points) 
(draw-blg-outllne) ;0ut11ne arrow 

(when 'do-the-strlpes* 

;; Bind distance betvreen stripes 
(let ((*str1pe-d» *str1pe-d1stance*)) 
(stripe-arrowhead) ;Str1pe head 

(str1pe-b1g-arrow-shaft)))))) ;Str1pe shaft 

(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(multlple-value-blnd 

(•plx* 'ply* •pZx* *pZy* 'pSx* "pSy* «p6x* •p6y) 

( compu te-arrowhead-pol nts ) 
(draw-outline) ;(hit11ne arrowhead 

(when *do-the-str1pes* 

;; Calculate distance between stripes 
(let ((*str1pe-d* (compute-strlpe-d))) 
(stripe-arrowhead) ; Stripe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 
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Calculates horizontal distance between stripes. 
Distance Is a fraction of the distance between stripes for the 
large arrow. The divisor depends on the level of recursion. 
Distance divides length of top edge evenly when possible to 
maintain continuity between head and shaft of arrow, 
(defun compute-strlpe-d () 

;; Distance should be at least 3 pixels so that there Is some 
;; white space between lines. 
(If (i 'stripe-distance* 3) 
3 

;; First find a fraction of •STRIPE-DISTANCE* that depends 
;; on recursion level 

(loop for dist s (fixr (// *str1pe-d1stance* 

(selectq *depth* 
(0 2) 
(1 4) 
(2 2) 
(3 1.5) 
(4 1.5) 

(otherwise 2)))) 
;; Increment If It doesn*t divide "TOP-EDGE* evenly 
then (1-1- dist) 

when (s (\ *top-edge* dist)) 
;; Stop when no remainder. Don*t return a value 
;; less than 3. 
do (return (If (^ dist 3) 3 dist))))) 



3. Replace *stripe-distaiice* with *$tripe-d* in the functions 
stripe-arrowhead and draw-arrow-shaft-stripes. 



(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x a (- *pOx* *top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from "pOx* by *str1pe-d* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom *pOy* by *str1pe-d* 

;; Draw a stripe 

do (draw-arrowhead- lines start-x end-y))) 
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(defun draw-arrow-shaft-stripes 

(left-x top-y right-x bottom-y) 
.. p^fifi y-coord of starting point of stripe. Don*t go 
;: below the bottom of the triangle. 

(loop for start-y from top-y by «str1pe-d* above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x downfrom rIght-x by «str1pe-d* 
;; Draw a stripe 
do (draw-arrow-shaft- lines 

left-x start-y end-x bottom-y))) 



We adjust the stripe density in three steps: 



1. Define two new constants for each arrow, 'dl* and •d2*. *dl* represents 
the stripe density, or the proportion of the distance between stripes that is 
black, at the upper right of each arrow. •d2* represents the density at 
lower left for each arrow. We estimate Ml* to be 0.15 and ♦dl* to be 
0.75. 

(def const 'dl* 0.15 
■Proportion of distance between upper right stripes that Is black") 

(def const *d2* 0.75 
"Proportion of distance between lower left stripes that Is black") 

2. Define a function, compote-nlines, that returns the number of adjacent 
lines that make up a stripe to be drawn. This function calls another, 
compote-dens, to calculate the proportion of the distance between stripes 
that is black. This proportion is a function of the petition of the stripe 
between the upper right and lower left of the arrow, compate-nlines 
multiplies this proportion by •strlpe-d* to determine the number of lines 
that make up the stripe, lliis nimiber must be at least one and less than 
*stripe-d* minus one. 

The argument to compate-nlines represents the horizontal position of the 
stripe to be drawn between the upper right and lower left of the arrow. 
Imagine the top edge of each arrow projected to the left beyond the 
arrowhead. Imagine each stripe projected to the upper left until it 
intersects with the extended top edge. The argument to compate-nlines is 
the x-coordinate of this intersection. •pOx* is the x-coordinate of this 
intersection for the top right comer of each arrow, where the stripe density 
is •dl*. •x2* is the x-coordinate of this intersection for the lower left 
stripe in each arrow, where the density is *d2*. The x-coordinate for each 
stripe must be between *pOx* and *x2*, and the density must be between 
•dl* and ^2*. 

(defvar •xZ* nil 
" X-coord inate of projection of lower left stripe on top edge") 
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(dofufi drawblg-arrow () 

;; Determine coordinates of arrowhead vertexes 
(Iiu1t1p1e->va1ue-b1nd 
(•plx* 'ply* 'pZx* 'pay* 'pSx* 'pSy* 'pex* •p6y«) 

( conpute-arrowhead-polnts ) 
;; Determine coordinates of shaft vertexes 
(multlple-value-blnd ("pax* 'pSy* •p4x« •p4y«) 
(compute-arrow- shaft-points) 
(draw-big-out line) ;0ut11ne arrow 

(when sdo-the-strlpes* 

;; Bind distance between stripes and x-coord of 
;; projection of last stripe onto top edge 
(let (('strlpe-d* 'stripe-distance*) 

(•x2* (- "pOx* •top-edge* nop-edge*))) 
(stripe-arrowhead) ;Str1pe head 

(str1pe-b1g-arrow-shaft)))))) ; Stripe shaft 

(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(multlple-value-blnd 
(•plx« "ply* 'pZx* "pZy* "pSx* "pSy* 'pex* "pey") 

( compu te-ar rowhead-po 1 n ts ) 
(draw-out Tine) ;0ut11ne arrowhead 

(when 'do-the-strlpes* 

;; Calculate distance between stripes and x-coord of 
;: projection of last stripe onto top edge 
(let ((*str1pe-d* (compute-str1pe-d)) 

(•x2« (- 'pOx* nop-edge* *top-edge*))) 
(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 



Calculates the number of lines that compose each stripe. 
Calls CONPUTE-DENS to calculate the proportion of distance 
bet««een stripes to be filled, then multiplies by the actual 
distance between stripes. Kakes sure that there Is at least 
one line and that there aren*t too many lines to leave some 
white space, 
(defun compu te-n lines (x) 

:: Call CONPUTE-DENS and multlpTy resuTt by 'strlpe-d* 
(let ((nT (fix (• 'strlpe-d* (compute-dens x))))) 
;; Supply at least one Tine 
(cond Hi nT 1) 1) 

;; But Teave some white space bettraen Tines 
((i nT (- "strlpe-d* 1)) (- 'strlpe-d* 2)) 
(t nl)))) 
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Calculates proportion of distance filled In between each stripe. 
The argunent Is the x-coordlnate of the projection of the current 
stripe onto the line formed by the top edge. Determines %<here the 
projection of the current stripe Is on this line In relation to the 
distance from first to last stripes in the arrow. Multiplies this 
fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe, 
(defun conpute-dens (x) 
(♦ -dl* (• (- 'dZ* 'dl*) 

(// (- X 'pOx') (float (- 'xZ* •pOx*)))))) 



3. For each function that draws a stripe, replace the sending of one 
show-lines message by a loop that might send several Determine the 
number of messages each function should send by calling compote-nlines. 



(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x « (- 'pOx* *top-edge«) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from 'pOx* by "strlpe-d* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom "pOy* by "strlpe-d* 

;; Find number of lines In the stripe 

for nllnes > (compute-n lines start-x) 

;; Draw the lines that make up the stripe 

do (draw-arrowhead- lines nllnes start-x end-y last-x))) 

(defun draw-arrowhead- lines (nllnes start-x end-y last-x) 
;; Set up a counter 
(loop for 1 from below nllnes 

;; Find starting x-coord, subtracting counter from first 

;; x-coord 

for first-x a (- start-x 1) 

;; Hake sure we don't go past the end of the arrowhead 

while (< last-x fIrst-x) 

;; Draw a line 

do (send 'dest* *:show-11nes 

fIrst-x "pOy* 'pOx* (- end-y 1)))) 
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(defun str1pe*b1g-arrow-shaft-1ert () 

;; Set up a counter for depth. Oon*t exceed Mxlmun recursion 

;; level. 

(loop for shaft-depth fron below 'nax-depth* 

;; Find current top edge and Its fractions 

for top-edge > 'top-edge* then (// top-edge 2) 

for top-edge-2 « (// top-edge 2) 

for top-edge-4 s (// top-edge 4) 

;; Find coordinates of apex of triangle 

for apex-x « •p2x« then (- apex-x top-edge-2) 

for apex-y « •p2y« then (- apex-y top-edge-2) 

;; Find x-coord of bottom right vertex 

for right-x ■ (♦ apex-x top-edge-4) 

;; Find y-coord of bottom edge of triangle 

for bottom-y ■ (- apex-y top-edge-4) 

;; Find the x-coord of the projection of the first 

;; stripe onto top edge 

for xoff ■ (- 'pOx* *top-edge*) then (- xoff top-edge) 

;; Stripe each triangle 

do (draw-b1g-arrow-shaft-str1pes-1eft 

top-edge-4 apex-x apex-y rIght-x bottom-y xoff))) 

(defun draw-blg-arrow-shaft-strlpes-left 

(top-edge-4 apex-x apex-y rIght-x bottom-y xoff) 
(loop with half-distance ■ (// •stripe-distance* 2) 
;; Find x-coord of last stripe In triangle 
with last-x « (- apex-x top-edge-4) 
;; Find x-coord of top of each stripe, decrementing 
;: from the apex by HALF the horizontal distance 
;; bettraen stripes. Stop at last stripe, 
for start-x from apex-x by half-distance above last-x 
; ; Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
;; Find x-coord of endpoint of stripe 
for end-x downfrom rIght-x by 'stripe-distance* 
;; Find number of lines in the stripe 
for nllnes « (compute-n lines (- xoff (- rIght-x end-x))) 
;; Draw a stripe 
do (draw-blg-arrow-shaft-llnes-left 

nllnes start-x start-y end-x bottom-y last-x))) 
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(defun draw-blg-arrow-shaft-llnes-left 

(nllnes start-x start-y end-x end-y last-x) 
;; Set up two counters °- we need to draw two lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find x-coord of top of first line In stripe 
for first-x « (- start-x 1) 
;; Don*t exceed number of lines In stripe 
while « 12 nllnes) 

;; Don*t go past the end of the triangle 
while (< last-x fIrsVx) 
;; Draw a line 

do (send 'dest* 'tshow-Hnes fIrst-x (- start-y 1) 
(- end-x 12) end-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpolnts of the lines so the diagonal 
edge looks neat, 
(send 'dest* *:show-11nes fIrst-x (- start-y 1 1) 
(- end-x 12 1) end-y))) 



(defun str1pe-b1g-arrow-shaft-r1ght () 
;; Set up a counter for depth. Don*t exceed maxlnum recursion 
;; level, 
(loop for shaft-depth from below *max-depth« 

;; Find new top edge and Its fractions 

for top-edge » 'top-edge* then (// top-edge 2) 

for top-edge-2 « (// top-edge 2) 

for top-edge-4 « (// top-edge 4) 

;; Find coords of top point of triangle 

for start-x « (♦ •p2x» top-edge-4) 

for top-y « (- •p2y« •top-edge-4* ) 

then (- top-y tpp-edge-2 top-edge-4) 

;; Find x-coord of projection of first stripe onto 

;; top-edge 

for xoff « (- 'pOx* "top-edge*) then (- xoff top-edge) 

;; Stripe the triangle 

do (draw-b1g-arrow-shaft-str1pes-r1ght 

top-edge-2 top-edge-4 start-x top-y xoff))) 
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(defun draw-blg-arrow-shaft-strlpes-rlght 

(top-edge-2 top-edge-4 start-x top-y xoff ) 
(loop with half •distance a (// *str1pe-d1stance* 2) 
;; Find y-coord of last stripe In triangle 
with last-y « (- top-y top-edge-2) 
;; Find y-coord of starting point of stripe. Don*t go 
;; past the end of the triangle. 

for start-y froa top-y by 'stripe-distance* above last-y 
;; Find coords of ending point of the stripe, decrementing 
;; by HALF the horizontal distance between stripes 
for end-x downfron {* start-x top-edge-4) by half-distance 
for end-y downfron (- top-y top-edge-4) by half-distance 
;; Find number of lines that make up the stripe 
for nllnes « (conpute-nllnes (- xoff (- top-y start-y))) 
;; Draw a stripe 
do (<^aw-b1g-arrow-shaft- lines-right 

nllnes start-x start-y end-x end-y last-y) )) 



(defun draw-blg-arrow-shaft-llnes-rlght 

(nllnes start-x start-y end-x end-y last-y) 
;; Set up two counters — we need to draw t%«o lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find y-coord of ending point of line 
for stop-y ■ (- end-y 1) 

;; Don*t exceed number of lines In the stripe 
While « 12 nllnes) 

:; Don*t go past the bottom of the triangle 
while (< last-y stop-y) 
;; Draw a line 

do (send 'dest* *:show-11nes start-x (- start-y 12) 
(- end-x 1) stop-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpolnts of the lines so the diagonal 
edge looks neat, 
(send "dest* *:show-11nes start-x (- start-y 12 1) 
(• end-x 1 1) stop-y))) 
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(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Don't exceed naxlnun 

;; recursion level. 

(loop for shaft-depth from 'depth* below •laax-depth* 
;; Calculate fractions of new top edge 
for top-edge-2 > *top-edge-2* then (// top-edge-2 2) 
for top-edge-4 ■ (// top-edge-2 2) 
;; Find coords of top left point of triangle 
for left-x « •p2x* then (- left-x top-edge-4) 
for top-y « *p2y* then (- top-y top-edge-2 top-edge-4) 
;; Find coords of botton right point of triangle 
for right-x « (♦ left-x top-edge-2) 
for botton-y « (- top-y top-edge-2) 

;; Find x-coord of projection of first stripe onto top edge 
for xoff ■ (- •pOx* 'top-edge*) 
then (- xoff top-edge-2 top-edge-2) 
;; Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y rIght-x bottom-y xoff))) 



(defun draw-arrow-shaft-stripes 

(left-x top-y rIght-x botton-y xoff) 
;; Find y-coord of starting point of stripe. Don*t go 
;; below the botton of the triangle. 

(loop for start-y from top-y by *str1pe-d1stance* above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x downfron rIght-x by *5tr1pe-d* 
;; Find nimber of lines In the stripe 
for n lines ■ (conpute-n lines (- xoff (- r1ght-x end-x))) 
;; Draw a stripe 
do (draw-arrow-shaft- lines 

nllnes left-x start-y end-x botton-y))) 



(defun draw-arrow-shaft-llnes 

(nllnes left-x start-y end-x bottoa-y) 
;; Set up a counter. Don't exceed nunber of lines In the stripe, 
(loop for 1 fron below nllnes 

;; Find x-coord of ending point of the line 
for last-x « (- end-x 1) 

;; Don't go past the left edge of the triangle 
%«h11e « left-x last-x) 
;; Draw a line 

do (send *dest* *:show-11nes left-x (- start-y 1) 
last-x bottoa-y))) 



Figure 3 (page 48) shows the output of the pto&zm with stripes of varying spacing and 
thickness. 

At this stage in developing the program we define new functions, constants, and variables. But 
most of the work consists of changing existing code. Often you need to make similar changes 
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Figure 3. Program output with stripes of varying spacing and density. 
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to several functions: you add an argument or replace sending one menage by a loop that sends 
several. In this case we are refining a new program, but when maintaining existing code you 
must also make selective or global changes. The most helpful Lisp Machine facilities are those 
for finding out about existing code (section 2.6, page 28) and for editing code (section 2.8, 
page 49). 

2.8 Editing Codo 

The features we discussed in sections 22 (page 7) and 2.4 (page 19) are useful mainly in 
composing new code. The features we described in section 2.6 (page 28) are helpful in both 
writing and editing code. In this section we discuss features that are likely to be most useful in 
editing existing code. 

2.8.1 identifying Changed Code 

Two pairs of List and Edit commands find or edit changed definitions in 
buffers or files. By default, the commands find changes made since the file 
was read; use numeric arguments to find definitions that have changed since 
they were last compiled or saved. 

Example 

After defining the routine that calculates the number of lines that compose 
each stripe, we changed many functions to call that routine and draw the 
appropriate number of lines. We want to look over the changes before 
recompiling the edited definitions. We use Edit Changed Definitions Of 
Buffer («-X). 

Reference 

List Changed Definitions Of Buffer (n-X) 

Lists definitions in the buffer that 

have changed since the file was read. 

Press C-. to edit the definitions 

listed. 

Edit Changed Definitions Of Buffer (m-X) 

Prepares for editing definitions in the 
buffer that have changed. Press c-. 
to edit subsequent definitions. 

List Changed Definitions (m-X) L»ts definitions in any buffer that 

have changed since the files were 
read. Press c-. to edit the 
definitions listed. 

Edit Changed Definitions (m-X) Prepares for editing definitions in any 

buffer that have changed. Press c-. 
to edit subseqtKnt definitions. 

Print Modifications (n-X) Dispbys lines in the current buffer 
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Source Compare (n-X) 



Source Compare Merge (m-X) 



that have changed since the file was 
read. 

Compares two buffers or files, listing 
differences. 

Compares two buffers or files and 
merges differences into a buffer. 



2.8.2 Searching and Replacing 

Many of the facilities discussed in section 2.6 (page 28), particularly the 
series of List and Edit commands, are useful for displaying and moving to 
code you wish to edit. The commands we discuss here find and replace 
strings. Tags tables offer a convenient means of making global changes to 
programs stored in more than one file. Use Select All Buffers As Tag 
Table (n-X) to create a tags table for all buffers read in. Use Select System 
As Tag Table (m-X) to create a tags table for all Hies in a system. (For 
information on systems, see the Lisp Machine Manual, chapter 24, page 406.) 



Exampie 

We have defined *strlpe-d*, and we want to replace some occurrences of 
the constant *5tripe-distance* by the variable *8trlpe-d*. We use Query 
Replace (jt-?^ to find each occurrence of *stripe-distance*. By pressing 
SPfK£, we replace *stripe-distuice* by *stripe-d* in functions like 
stripe-arrowhead. By pressing Rl^CNJT, we leave *stripe-distaiice* in place 
in functions like draw-big-arrow-shaft-stripes-left. 



Reference 

List Matching Lines (m-X) 



Incremental Search (c-S) 



Reverse Search (c-R) 



Displays the lines (following point) in 
the current buffer that contain a 
string. 

Prompts for a string and moves 
forward to its first occurrence in the 
buffer. Press c-S to repeat the 
search with the same string. Press 
c-R to search backward with the 
same string. After you invoke the 
command, if c-S is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 

Prompts for a string and moves 
backward to its last occurrence in the 
buffer. Press c-R to repeat the 
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Tags Search (m-X) 
Replace (c-2) 

Query Replace (nrZ) 



Tags Query Replace (m-X) 



search with the same string. Press 
c-S to search forward with the same 
string. After you invoke the 
command, if c—R is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 

Searches for a string in all files listed 
in a tags table. 

In the buffer, replace all occurrences 
(following point) of one string by 
another. 

In the buffer, replaces occurrences 
(following point) of one string by 
another, querying before each 
replacement. Press HELP for possible 
response. 

In files listed in a tags table, replaces 
occurrences of one string by another, 
querying before each replacement. 



Select All Buffers As Tag Table (a>-X) 



Select System As Tag Table (ra-X) 



Create a tags table for all buffers in 
Zmacs. 

Creates a tags table for files in a 
system defined by def system. 



2.8.3 Moving Text 



2.8.3.1 Moving through Text 

To move short distances through text, you can use the Zmacs commands for 
moving by lines, sentences, paragraphs. Lisp forms, and screens, or you can 
click left to move point to the mouse cursor. To move longer distances, you 
can move to the beginning or end of the buffer or use the scroll bar. To go 
to another buffer, use Select Buffer (c-X B). To switch back and forth 
between two buffers, use Select Previous Buffer (c-ki-L). 



Suppose you want to record a location of point so that you can return to 
that location later. Two techniques are particularly useful: 

• Store the location of point in a register. Use Save Position (c-X S) to store 
point in a register. Use Jump to Saved Position (c-X J) to return to that 
location. 

• Use n-SPRCE to push the location of point onto the mark stack. Later, you 
can use c-ii-SPfCE to exchange point and the top of the mark stack. c-U 
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c-SPRCE pops the mark stack; repeated execution moves to previous marks. 
Note: Some Zmacs commands other than c-SPRCE push point onto the 
mark stack. When point is pushed onto the mark stack, the notification 
"Point pushed" appears below the mode line. 



Reference 

Select Buffer (c-X B) 



Select Previous Buffer (c-m-L) 



Save Position (c-X S) 



Moves to another buffer, reading the 
buffer name from the minibuffer. 
With a numeric argument, creates a 
new buffer. 

Moves to the previously selected 
buffer. 

Stores the position of point in a 
register. Prompts for a register name. 



Jump To Saved Position (c-X J) 



Moves point to a position stored in a 
register. Prompts for a register name. 



Set Pop Mark (c-SPfiCE) With no argument, sets the mark at 

point and pushes point onto the mark 
stack. With an argument of c-U, 
pops the mark stack. 

Push Pop Point ExpUcit («-SPflCE) With no argimient, pushes point onto 

the mark stack without setting the 
mark. With an argument /i, 
exchanges point with the nth position 
on the mark stack. 

Move To Previous Point (c-»-SPflCE) Exchanges point and the top of the 

mark stack. 



Swap Point And Mark (c-X c-X) 



Exchanges point and mark. Activates 
the region between point and mark. 
Use Beep (c-G) to turn off the 
region. 



2.8.3.2 Killing and Yanking 

When you need to repeat text, you usually want to copy it rather than type 
it anew. The most common facilities for copying text are the commands for 
killing and yanking. Commands that kill more than one character of text 
push the text onto the kill ring. c-Y yanks the last kill into the buffer. 
After a c-Y command, m-Y deletes the text just inserted, yanks the previous 
kill, and rotates the kill ring. 
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Example 

In the function draw-big-arrow-shaft-lines-left, we send two :show-lines 
messages on each iteration. The purpose is to arrange the starting points of 
the lines along the diagonal edge so that they lie as closely as possible on a 
45-degree line. The second send expression is nearly identical to the Hrst. 
Instead of typing a new expression, we copy and edit the first one. We 
follow these steps: 

1. Position the ou'sor after the close parenthesis that ends the first send 
expression. 

(defun draw-blg-arrow-shaft-llnes-left 

(nllnes start-x start-y end-x end-y last-x) 



do (send 'dest* *:shovf-11ne$ first-x (- start-y 1) 
(- end-x 12) end-y) 

2. Use c-n-RlBOUT to kill the send expression and pusL it onto the kill ring. 

(defun draw-blg-arrow-shaft-llnes-left 

(nllnes start-x start-y end-x end-y last-x) 



do 

3. Use c-Y to restore the expression. 

(defun draw-big-arrow-shaf t-1 ines-lef t 

(nllnes start-x start-y end-x end-y last-x) 

do (send «dest« *: show- lines fIrst-x (- start-y 1) 
(- end-x 12) end-y) 

4. Use LINE to move to the next line and indent. 

5. Use c-Y to insert a copy of the send expression. 

(defun draw-big-arrow-shaf t-1 Ines-lef t 

(nllnes start-x start-y end-x end-y last-x) 



do (send 'dest* ': show- lines first-x (- start-y 1) 

(- end-x 12) end-y) 
(send 'dest* 'rshow-lines first-x (- start-y 1) 

(- end-x 12) end-y) 
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6. Edit the second send expression. 



( def un draw-bl g-arrow-shaf t- 1 1 nes- 1 eft 

(nllnes start-x start-y end-x end-y last-x) 



do (send *dest* *:show-11nes first-x (- start-y 1) 

(- end-x 12) end-y) 
(send *dest« *: show- 11 nes fIrst-x (- start-y 11) 

(- end-x 12 1) end-y))) 



Example 

Suppose we have an existing program in which we have already defined the 

function compate-nlines. We can copy the function in three ways: 

• Use c-«-K or c-«-RUBOUT to kill the definition. Use c-Y to restore it. Go 
to the new buffer. Use c-Y to insert a copy of the deHnition. 

• Use c-n-H to mark the deHnition. Use n-U to push it onto the kill ring. 
Go to the new buffer. Use c-Y to insert a copy of the definition. 

• Click middle on the first or last parenthesis of the definition to mark the 
definition. Click double-middle to push it onto the kill ring. Move to the 
new buffer. Click double-middle to insert a copy of the definition. 



Reference 

Kill Sexp (c-Bi-K) Kills forward one or more Lisp 

expressions. 

Backward Kill Sexp (c-»-RUBOUT) Kills backward one or more Lisp 

expressions. 



Mark Definition (c-n-H) 
Save Region (m-M) 
Yank (c-Y) 



Yank Pop (i»-Y) 



Puts point and mark around the 
current defuiition. 

Pushes the text of the region onto the 
kill ring without killing the text. 

Pops the last killed text from the kill 
ring, inserting the text into the buffer 
at point. With an argument n, yanks 
the nth entry in the kill ring. Does 
not rotate the kill ring. 

After a c-Y command, deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring. Repeated 
execution yanks previous kiUs and 
rotates the kill ring. 
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[Region (M2)] When region is defined, pushes the 

text of region onto the kill ring 
without killing the text (like n-U). 
Repeated execution has the following 
effects: 

• First repetition: kills the text of 
region, pushing the text onto the kill 
ring (like c-W) 

• Second repetition: pops the text of 
region from the kill ring, inserting the 
text into the biiffer at point (like 
c-Y) 

• Third and subsequent repetitions: 
delete the text just inserted, yank 
previously killed text from the kill 
ring, and rotate the kill ring (like 
«-Y) 

If no region is defined, pops the last 
killed text from the kill ring, inserting 
the text into the buffer at point (like 
c-Y). Repeated execution deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring (like i»-Y). 

2.8.3.3 Using Registers 

Using c-Y and mi-Y to copy text can become tedious when you have to 
rotate through a long kill ring to find the text you need. Another method, 
especially useful when you want to copy a piece of text more than once, is 
to save and restore the text using registers. 



Reference 

Put Register (c-X X) 



Open Get Register (c-X G) 



Copies contents of the region to a 
register. Prompts for a register name. 

Inserts contents of a register into the 
current buffer at point. Prompts for 
a register name. 



2.8.3.4 Copying Buffers and Files 

Use Insert File (m-X) to place the contents of an entire file in your buffer. 
You can copy the contents of a buffer in two ways: 
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• Use Insert Buffer (m-X), naming the buffer you want to copy. 

• Use c-X H to mark the buffer you want to copy. Use »-M to push its text 
onto the kill ring. Move to the new buffer. Use c-Y to insert a copy of 
the text. 



Reference 

Mark Whole (c-X H) 

Insert Buffer (m-X) 



Insert File (m-X) 



Marks an entire buffer. 

Inserts contents of the speciHed 
buffer into the current buffer at 
point. 

Inserts contents of the specified file 
into the current buffer at point. 



2.8.4 Keyboard Macros 

Sometimes you need to perform a uniform sequence of commands on several 
pieces of text. You can save keystrokes by converting the sequence to a 
keyboard macro and installing it on a single key. If you anticipate using a 
macro often, you can write Lisp code to define it in an init file. If you 
frequently use particular extended commands, install them on single keys 
with Set Key («-X). 



Reference 

Start Kbd Macro (c-X <) 

End Kbd Macro (c-X >) 

Call Last Kbd Macro (c-X E) 
Name Last Kbd Macro (n-X) 

Install Macro (n-X) 

Install Mouse Macro (n-X) 



Deinstall Macro (n-X) 



Set Key (n-X) 



Begins recording keystrokes as a 
keyboard macro. 

Stops recording keystrokes as a 
keyboard macro. 

Executes the last keyboard macro. 

Gives the last keyboard macro a 
name. 

Installs on a key the last keyboard 
macro or a named macro. 

Installs a keyboard macro on a mouse 
click (such as L2). When you click 
to call the macro, point moves to the 
position of the mouse cursor before 
the macro is executed. 

Deinstalls a keyboard macro from a 
key or a mouse cUck. 

Installs an extended command on a 
single key. Use HELP C to look for 
unassigned keys. 
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2.8.5 Using Multiple Windows 

2.8.5.5 Multiple Buffers 

Sometimes when editing you move often between two buffers. You might 
want to see the two buffers at the same time rather than switch between 
them. A common use of multiple-window display is to edit source code 
while viewing compiler warnings (see section 4.1, page 71). 



Example 

We add a new show-lines message to the program but forget what 
arguments the message takes. We want to display the source code for the 
message handler on the same screen as our program code. We use c-X 2 to 
create another window and move to it. We use Edit Methods (m-X) to find 
the source code for the method that handles rshow-Unes (see section 5.2.2, 
page 129). 



Example 

After finishing the program, we collect a file of bug reports from users. We 
want to use these reports in correcting our program code. We create two 
windows, one displaying the program code and the other the bug-report file. 
We edit the program code, using c-«-V to scroll the bug-report window as 
we correct each bug. 



Reference 

Split Screen (m-X) Pops up a menu of buffers and splits 

the screen to display the buffer you 
select. 

Two Windows (c-X 2) Creates a second window, with the 

current buffer on top and the 
previous buffer on the bottom. Puts 
the cursor in the bottom window. 

View Two Windows (c-X 3) Creates a second window, with the 

current buffer on top and the 
previous buffer on the bottom. Puts 
the cursor in the top window. 

Modified Two Windows (c-X 4) Creates a second window and visits a 

buffer, file, or tag there. Displays the 
current buffer in the top window. 

Other Window (c-X 0) Moves to the other of two windows. 

Scroll Other Window (c-ni-V) Scrolls the other of two windows. 

One Window (c-X 1) Returns to one-window display, 

selecting the buffer the cursor is in. 
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2.8.5.6 Zmacs and Other Windows 

Use [Split Screen] or [Edit Screen] from a system menu to display an editor 
window on the screen with other kinds of windows. 

Example 

In testing new program functions, we want to have the current version of 

the figure on the same screen as the program code. We use [Split Screen] 

from a system menu to add a Lisp Listener to the screen. We move 

between windows by clicking left on the window to which we want to 

move. 

We evaluate (pkg-goto 'graphics) and then (do>arrow) in the Lisp 
Listener. We adjust the arguments to draw-arrow-graphic so that the 
arrow fits neatly into the Lisp Listener window. 

(defun do-arrow () 
(let (('dest* (make- Instance * screen-arrow-output))) 
(send tern1na1-1o *:c1ear-screen) 
(draw-arrow-graphic 640 1300 1850))) 

Figure 4 (page 59) shows the appearance of the screen with graphic output 
in a Lisp Listener and source code in a Zmacs buffer. 

To return to displaying only the Zmacs window, we use [Split Screen] with 
the existing Zmacs buffer as the only element 



Reference 

[Split Screen / Lisp / Existing Window / Existing Zmacs Buffer / Do It] 

(from a system menu) 
Adds a Lisp Listener to a screen 
displaying an existing Zmacs buffer. 

[Split Screen / Existing Window / Existing Zmacs Buffer / Do It] (from a 

system menu) 

Resumes one-window display of an 
existing Zmacs buffer. 

2.8.5.7 Other Displays 

The window system allows you to use menus, choose-variable-values 
windows, and other multiple-window displays in executing programs. See 
Introduction to Using the Window System and Lisp Machine Choice Facilities 
for details. See chapter 5 (page 101) for examples of simple uses of 
windows, including choose-variable-values windows. 
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Calculates the nunber of lines that conpose each stripe. 
Calls COMPUTE-DENS to calculate the proportion of distance 
between stripes to be filled, then Multiplies by the actual 
distance between stripes, flakes sure that there Is at least 
one line and that there aren't too nwty lines to leave sone 
white space, 
(defun conpute-n lines (x) 

;: Call COnPUTE-OENS and multiply result by s8TRIPE-D< 
(let (<nl (fix (« «str1pe-d* (conpute-dens x))))) 
;; Supply at least one line 
(cond ((i nl 1) 1) 

;; But leave sone white space between lines 
iil nl (- «str1pe-d« 1)) (- «str1pe-d« 2)) 
(t nl)))) 

Calculates proportion of distance filled In between each stripe. 
The argument Is the x-coordlnate of the projection of the current 
stripe onto the line forned by the top edge. Determines where the 
projection of the current stripe Is on this line In relation to the 
distance fron first to last stripes In the arrow. Multiplies this 
fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe, 
(defun conpute-dens (x) 
(♦ «dl« (« (- «d2« «dl») 

(•/ (- X «pex«) (float (- «x2« tp0x«)))))) 



ZHflCS (LISP) pcodex.l •dess/doc^workstyles/ UIXEN: « [More above and below] 



.zMove point, L2:Move to point, M:Mark thing, M2:Save/K11 Wank, R:Menu, R2:Sy8ten n^no 
-_ t GRAPHICS: TyT 



u:iiave poini,, U£:r 
08/1 F/BS 18:06:25 



Figure 4. Using multiple windows to test the program while viewing the source code. 
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3. Compiling and Evaiuating Lisp 

When should you compile code, and when evaluate it? 

The main job of the compiler is to convert interpreted functions into compiled functions. An 
interpreted function is a list whose first element is lambda, naned-laobda, sabst, or 
named-sobst. These functions are executed by the Lisp evaluator. The most common 
interpreted functions you deHne are named-lambdas. When you load a source file that 
contains defan forms or when you otherwise evaluate these forms, you create named-lambda 
functions and define the function specs named in the forms to be those functions. 

Compiled functions are Lisp objects that contain programs in the Lisp Machine instruction set 
(the machine language). They are executed directly by the microcode. Compiling an 
interpreted ftmction (by calling the compiler on a function spec) converts it into a compiled 
function and changes the definition of the function spec to be that compiled function. 

You seldom compile functions directly. Instead, you compile either regions of Zmacs buffers or 
source files. 

• Compiling a region of a Zmacs buffer (or the whole buffer) causes the 
compiler to process the forms in the region, one by one. This processing has 
side effects on the Lisp environment We summarize the compiler's actions 
in section 3.1.1 (page 62). 

• Compiling a source file translates it into a binary file. With some 
exceptions, this processing does not have side effects on the Lisp 
environment at compile time. When you load a compiled file that defines 
functions, you create comfnled rather than interpreted functions and define 
function specs to be those compiled functions. In other respects, loading a 
compiled file has essentially the same effects as loading a source file 
(evaluating the forms in the file). We discuss compiling files in section 3.1.2 
(page 65). 

Most Symbolics programmers compile all their program code. The compiler checks extensively 
for errors and issues warnings that help detect bugs like typographical errors, unbound symbols, 
and faulty Lisp syntax. Compiled code runs faster and takes up less storage than interpreted 
code. You can compile code in portions and decide at compile time whether or not to save the 
compiler output in a binary file. 

The most common use for interpreted functions is stepping through their execution. You 
cannot step through the executicm of a compiled function. If a function is compiled, you can 
read its definition into a Zmacs buffer, evaluate the definition, and then step through a 
fuiMtion call. 

In addition to evaluating definitions to create interpreted functions, you might need to evaluate 
forms to test a program or find information about a Lisp object (Unless you are using the 
Stepper, fimctions that you call during these evaluations are usually compiled.) You can 
evaluate a form in a Lisp Listener, a breakpoint loop,.or the minibuffer. 

See the Usp Machine Manual, chapter 10^ page 136, for more information on functions. 
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3.1 Compiling Lisp Code 

You can use Zmacs commands to compile code in a file or Zmacs buffer. Most Symbolics 
programmers compile code as soon as they have written enough to test. This practice lets them 
correct errors quickly and produce simple working versions of programs before adding more 
complex operations. A common command for incremental compiling from a Zmacs buffer is 
Compile Region (c-sh->C). If no region is defined, this command compiles the current 
definition. 

In addition^to compiling definiticMis as they write them. Symbolics programmers consider it 
good practice to recompile a function soon after effecting a change. Because recompiling a 
series of functions or an entire program can be time<onsuraing, it is easier and faster to make 
changes and then use a single command to recompile only the changed functions. Using 
Compile Changed Definitions Of Busier (n-sh-C) or Compile Changed Definitions (m-X) is 
easier in this case than recompiling each function separately or recompiling the entire buffer. 

The order in which you compile definitions can be important. For example, suppose you have 
a function that binds a variable you want to be treated as special. If you compile the function 
definition before compiling the variable declaration, the compiler treats the variable as local 
and generates incorrect output. For this reason you should usually put defvar and defconst 
forms at the beginning of a file or into a separate file to be compiled and loaded before 
function definitions. 

When editing a program, it is a good idea to load the entire program before you start work on 
it. When you compile new deHnitions or recompile edited ones, the compiler will have access 
to variable dechu'ations, macros, functions, and other information. You will also be able to use 
Zmacs commands and Lisp functions for finding infivmation about other parts of the program 
(see section 2.6, page 28). 

Sometimes when you compile a file, write large sections of code at once, or make many changes 
to a large program, compiling the code produces many warning messages. Chapter 4 (page 71) 
describes how Edit Compiler Warnings (m-X) lets you use the compiler warnings as a reference 
source for debugging. 

See the Lisp Machine Manual, chapter 16, page 197, for more information on the compiler. 

3.1.1 Compiling Code in a Zmacs Buffer 

Compiling a top-level form in a Zmacs buffer — using a command like 
Compile Region (c-sh-C) or Compile Buffer (m-X) — has side effects on 
the Lisp environment. Following is a summary of the compiler's actions: 

Form Action 

Macro form If the form is a list whose Hrst element b a 

macro, the compiler expands the form and 
processes this expanded form instead of the 
original. 

Function deHnition If the form is a list whose Hrst element is defan. 
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Macro defuution 



Special case 



Atom, comment fonn 
Other 



the compiler constructs a lambda-expression from 
the definition, converts the lambda-expression into 
a compiled ftmction, and defines the function spec 
named in the definition to be that compiled 
function. 

If the form b a list whose first element is macro, 
the compiler constructs a lambda-expression as the 
macro's expander function, converts the lambda- 
expre^on into a ^mpiled function, and defines 
the function spec named in the definition to be 
the macro. A defmacro form expands into this 
kind of form. 

Some forms, like eval-when, declare, and 
progn 'compile forms, have special meaning for 
the compiler. It handles each of these in a 
different way. (See the Li^ Machine Manual, 
chapter 16, page 197, for details.) 

The form is ignored. 

The form b evaluated. 



Example 

We have written some initial code for the controlling function of the 
calculation module: 

(defvar 'top-edge* nil 
"Length of the top edge of the arrow* } 

(defvar 'pOx* nil 
"X>coord1nate of point 0*) 

(defvar "pOy* nil 
■Y-coordlnate of point 0*) 

(defun draw-arrow-graphic (*top-edge* 'pOx •pOy*) 

(let ((nop-edge-2* (// *top-edge* 2)) 

(•top-edge-4* (// 'top-edge* 4))) 
(draw-big-arrow))) 



Because we have no other code in the buffer, we can compile these 
definitions using Onnpile Buffer (n*-X). If we had more code in the buffer, 
we could compile these definitions by setting the mark at one end and point 
at the other and using Compile Region (c-sh-C). 

The compiler displays the following framings: 
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For Function DRAW- ARROW-GRAPHIC 
The variable •T0P-ED6E-4* was never used. 
The variable •T0P-ED6E-2* was never used. 
The variable 'POX was never used. 

The following functions %#ere referenced but don*t seem defined: 
DRAW-BIG-ARROW referenced by DRAW-ARROW-GRAPHIC 

The first set of warnings indicates that the compiler is treating 
^top-cdge-2^ *top-cdge-4^ and ^pOz as local variables. We neglected to 
declare *top-cdgc-2* and *top-edge-4* special with def?ar; *pOz is of 
course a misspelling. The lack of a definition for draw-big-arrow is not 
surprising; we have yet to write that definition. 

We add the two def ftrs and correct the spelling of *pOx^. We compile the 
changes using Compile Changed Defuiitions Of Buffer (n-sh-C). The 
compiler now displays only one warning: 

The following functions «rare referenced but don't seen defined: 
0RAW-BI6-ARROW referenced by DRAW-ARROW-GRAPHIC 

We continue writing the program by defining draw-blg-arrow. 

Reference 

Compile Region (c~sh-C) Compiles the region. If no region is 

marked, compiles the current 
definition. 

[Zmacs Window / Compile Region] Compiles the region. If no region is 

marked, C(Hnpiles the current 
definition. 

Compile Changed Definitions Of Buffer (m-sh-C) 

Compiles all the definitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
compiled. 

Compile Changed Definitions (li-X) Compiles all the definitions in any 

Zmacs buffer that have changed since 
the definitions were last compiled. 

Compile Buffer (n-X) Compiles the current Zmacs buffer. 

Compile (e-X) [Zmacs Window (R)] Pops up a menu of options for 

compiling code in the current OMitext. 
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3.1 .2 Compiling and Loading a File 

Compiling a file, using Compile File (m-X) or compiler:compile-file, saves 
the compiler output in a binary file of canonical type :bin. For the most 
part, compiling a file does not have side effects on the Lisp environment. 
The basic difference between compiling a source file and compiling the same 
forms in a buffer is this: When yon compile a Hie, most function specs are 
not defined and most forms (except those within evtl-when (compile) 
forms) are not evaluated at compile time. Instead, the compiler puts 
instructions into the binary file that cause these things to happen at load 
time. You can load a source or binary file into the Lisp environment by 
using Load File (n-X) or load. You can compile a file and then load the 
resulting binary file by using compiler:complle-flle-load. 

Example 

In a previous session, we wrote the output routines for the program, saved 

them in a file, and compiled that file. Now we are writing the first 

calculation routines, and we want to test them. We need to load the Hie 

that contains the compiled code for the output routines. We use Load File 

(m-X). 

Suppose our two files are in the directory >Synbo1.lcs>exanplesy on Lisp 
Machine acne-blus. The file containing the output routines is arrow-out. 
The current 2^macs buffer, and the file containing the calculation module, is 
arrow-calc. When we type n-X load file (or a-X 1o f, using completion), 
Zmacs prompts for a file name: 

Load File: (Default Is ACNE-BLUE:>Synbo11cs>exaiiq)1es>arrowca1e) 

We type arrow-out, without a file type. The latest version of 
arrow-out.bin is loaded. If no compiled vision exists or if the latest 
compiled file is older than the latest source fQe, Zmacs offers to compQe the 
source file and then load the compiled version. 

Reference 

Compile File (n-X) Prompts for the name of a file and 

compiles that file, placing the 
compiled code in a file of canonical 
type :bln. 

(coaplleRCOBpilc-flle file-nami^ Compiles a file, placing the compiled 

code in a file of canonical type :biB. 

Load File (m-X) Prompts for a file name, taking the 

default from the current buffer. 
Offers to save the buffer if it has 
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changed since the file was last read or 
saved. Offers to compile the source 
file if no compiled version exists or if 
the source file was created after the 
latest compiled version. If you specify 
a nie type, loads the latest version of 
the file of that type. If you don't 
specify a file type, loads the latest 
version of the binary file (even if 
older than the latest source file); if no 
binary file exists, loads the latest 
source file. 

(load file-n^mte) Loads a file into the Lisp 

environment. If you spMnfy a file 
type, loads the latest version of the 
file of that type. If you don't specify 
a file type, loads the latest version of 
the binary file (even if older than the 
latest source file); if no binary file 
exists, loads the latest source file. 

(compiIer:complIe-file-lotd file-nam^ 

Compiles a file, placing the compiled 
code in a file of canonical type :biii. 
Loads the resulting binary file. 



3.2 Evaluating Lisp Code 



3.2.1 Evaluation and the Editor 

The most common reason for evaluating definitions in a Zmacs buffer is to 
step through the execution of the functions they define. Sometimes in 
debugging you want to proceed step by step through a function call, using 
step or the :step option to trace (see section 4.4.2, page 86). You can do 
this only with interpreted functions. If a function is compiled, you can use 
Edit Definition (m-. ) to read its definition into a Zmacs buffer. You can 
then evaluate the definition using Evaluate Region (c-sh-E). When you 
have finished stepping, you can recompile the definition. 

The evaluation of Lisp forms in the editing buffer or the minibuffer 
normally displays the returned values in the echo area (beneath the mode 
line near the bottom of the screen). Any output to standard-oatput during 
the evaluation appears in the editor typeout window. Two commands. 
Evaluate Into Buffer (m-X) and Evaluate And Replace Into Buffer (m-X), 
print the returned values in the Zmacs buffer at point. With a numeric 
argument, these commands also insert any typeout from the evaluation into 
the Zmacs buffer. 



Program Development Tools and Techniques 67 

Symbolics, Inc. 



Often while editing you need to evaluate forms other than definitions in a 
buffer. You need to call a function to test your program, or you need to 
call a function like describe to Hnd information about a Lisp object. (Of 
course, these functions need not be interpreted.) You can type forms to be 
evaluated in three ways: 

• Use m-ESCflPE to evaluate a form in the minibuffer. 

• Use SUSPEND to enter a Lisp breakpoint loop. You type forms that are 
read in the buffer's package and evaluated. Use RESUrc to return to the 
editor. 

• Use SELECT L or [Lisp] from a system menu to select a Lisp Listener and 
evaluate forms there. Use SELECT E or [Edit] from a system menu to 
return to the editor. 



Example 

We have found a bug in the program and suspect that it lits in the function 
do-arrows. We want to step through a call to that function, but it is 
compiled. We use Edit Definition (m-. ) to find the definition of do-arrows 
and Evaluate Region (c-sh-E) to evaluate the deHnition. We then step 
through a function call (see section 4.4.2, page 86). 

Example 

We have written and compiled the output routines and the initial code for 
the calculation module. We want to test the program as written so far. 
The top-level function to call is do-arrow. We can test the program in 
three ways: 

• Press m-ESCRPE and evaluate (do-arrow). The graphic output appears in a 
typeout window. We press ^>ftCE to restore the editing buffer to the 
screen. 

• Press SUSPEND to enter a Lisp breakpoint loop and evaluate (do-arrow) 
there. We press RESUME to return to the editor. 

• Press SELECT L to select a Lisp Listener. If the current package is not 
graphics, we Hrst evaluate (pkg-goto 'graphics) and then (do-arrow). We 
press SELECT E to return to the editor. 



Example 

We want to be sure that new function names do not conflict with other 
symbol names in the graphics package. Most of our function names 
contain the string "arrow". We want to find the symbol names that contain 
that string. We use ii-ESCfiPE, SUSPEND, or SELECT L and evaluate: 

(apropos "arrow" * graphics) 
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Reference 

Evaluate Region (c-sh-E) 



Evaluates the region. If no region is 
marked, evaluates the current 
deHnition. 



Evaluate Changed Definitions Of Buffer (n-sh-E) 

Evaluates all the deHnitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
evaluated. 



Evaluate Changed Definitions (m-X) 

Evaluate Buffer (m-X) 
Evaluate Into Buffer (n-X) 



Evaluates all the definitions in any 
Zmacs buffer that have changed since 
the deHnitions were last evaluated. 

Evaluates the current Zmacs buffer. 



Prompts for a Lisp form to evaluate 
and prints the returned values in the 
Zmacs buffer at point. 

Evaluate And Replace Into Buffer (m-X) 

Evaluates the Lisp form following 
point and replaces it with the printed 
representation of the values it returns. 



Evaluate Minibuffer (n-ESCflPE) 



Evaluate (n-X) [Zmacs Window (R)] 



SUSPEND 



Prompts for a Lisp form to evaluate 
in the minibuffer and displays the 
returned values in the echo area. 

Pops up a menu of options for 
evaluating code in the current 
context. 

Enters a Lisp breakpoint loop, where 
you can evaluate forms. The current 
package in the breakpoint loop is the 
same as in the previous context. Use 
r^SltC to return to the previous 
context. 



3.2.2 Lisp Input Editing 

When typing to a Lisp Listener you can use many editing commands to 
modify a form before you evaluate it You often repeat the same function 
calls or variations of similar function caUs when testing code. Instead of 
retyping these forms, you can use the Lisp input editor's ring of input 
entries to retrieve them within the same Lisp Listener. When you yank a 
previous form, the Lisp input editor places the cursor at the end of the form 
but omits the final close parenthesis or carriage return. You can then edit 
the form before typing the final delimiter to evaluate it. 
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Example 

We execute oxir program by calling the function do-trrow. We evaluate 
(do-arrow) once and would like to evaluate it again within the same Lisp 
Listener. We press c-C to yank the last form we typed. If that is not 
(do-arrow), we press n-C until (do-arrow appears, without the close 
parenthesis. We type a close parenthesis to begin the evaluation. 



Reference 

c-C Yanks the last form typed to the Lisp 

Listener. Excludes the final delimiter, 
allowing you to edit the form before 
evaluating it. With an argument n, 
yanks the ffth form in the ini»it ring. 
(This command is not available in 
Zmacs.) 

n-C After a c-C command, deletes the 

form just inserted, yanks the previous 
form from the input ring, and rotates 
the input ring. Repeated execution 
yanks previous forms and rotates the 
input ring. (This command is not 
available in Zmacs.) 
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4. Debugging Lisp Programs 

The Lisp Machine offers a variety of took for debugging Lisp programs. The kind of 
debugging aid you use depends on the application of the program. Bu^ might be more obvious 
in a graphics program than in a minor modification of some internal system function. 
Problems with a graphics programs are sometimes evident from the program's output. On the 
other hand, programs with a complex window system application might have bugs that are 
difficult to identify. 

Debugging aids are more appropriate for some kinds of bugs than for others. You commonly 
encounter three sorts of problems with a program: 

• The program does not compile correctly. You can use the compiler 
warnings database to edit axle before recompiling. 

• The program compiles, but nmning it signals an error. Usually errors 
invoke the Debugger, where you can examine stack frames, return values, 
disassemble code, call the editor, and perform other tasks. 

• The program runs but does not behave as it should. You can use many 
techniques for finding the problem, including conmienting out sections of 
code, tracing, stepping, setting breakpoints, disassembling, and inspecting. 
Often the most effective method is simply studying the source code. 

4.1 The Compiler Warnings Database 

The compiler sometimes produces many warning messages. The compiler maintains a database 
of these messages, organized by Hie. Each time you compile or recompile code, the compiler 
adds or removes warnings from the database, so that the database reflects the state of your 
program as of the last time you compiled it. 

If you want to save warnings in a file, you can use Compiler Warnings (m-X) to put them in a 
buffer and then write them to a file. When you make a system using make-system, you can 
use the :batch option to save compiler warnings in a file (see the Lisp Machine Manual, 
section 24,3, page 411). Use Load Compiler Warnings (m-X) to load compiler warnings into 
the database from a file. 

If compiler warnings exist in the database. Edit Compiler Warnings (m-X) lets you edit source 
code while consulting the corresponding warnings. The command splits the screen, with 
compiler warnings in one window and the source code to which the warnings apply in the 
other. As you finish editing each section of code, you press c-. . This displays the next 
warning in one window and the source code to which the next warning applies in the other 
window. When you reach the last compiler warning, pressing c-. returns the screen to its 
previous configuration. 

Example 

In section 3.1.1 (page 62), we discussed compiling the initial code for the 
calculation module of the sample program. Figure 5 (page 72) shows the 
result of using Edit Compiler Warnings (n-X) after compiling the buffer 
with the initial code. The compiler warnings are in the upper window and 
the source code in the lower window. 
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Uarnings for file V/IXEN: /dess>'doc/yorkstyles>'pcodeK.; 

I For Function DRfM-RRROU-GRRPHIC 

The variable *T0P-E0GE-4s was never used. 
The variable *T0P-ED6E-2* was never used. 
The variable *POX was never uded. 
ORflU-BIG-RRROU was referenced but not defined. 



«Conp 1 1 er-Uarn I ngs- i « 



(defun draw-arrow-graphic (*top-edge« *pBk «pOy<) 
(let ((«top-edge-2< (// *top-edge« 2)) 
(«top-edge-4» (// *top-edge* 4))) 
( cfr*aw-b I g-arrow) ) ) 



pcodex.l /dess/'doc/workstyles/ VIXEN; 

ZmCS (LISP) pcodeK.I <^dessXdoc/workstyles/ VIKEN: » 

Control-. Is now Edit warnings for next function. 

1 nore definition as well 

Point pushed 



:nove point, L2:nove to point, MiHark thing, n2:Save/'Ki I I/Yank, RiNenu, R2:Svsten nenu 
8/28/83 16:49:52 ron GRfiPHICS: Tyl 



Figure S. Edit Compiler Warnings (nt-K) splits the screen. The upper window contains 
compiler warning. The lower window contains the source code. 
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Reference 

Edit Compiler Warnings (la-X) 



Compiler Warnings (m-X) 



Load Compiler Warnings (m-X) 



Prepare to edit all source code that 
has produced compiler warnings. 
Lists each file whose code produced 
warnings and asks whether you want 
to edit that Hie. Splits the screen, 
with compiler warnings in the upper 
window and source code that 
produced those warnings in the lower 
window. Use c-. to display 
subsequent warnings and edit the 
applicable code. 

Puts compiler warning messages into a 
buffer and selects that buffer. 

Loads a file containing compiler 
warning messages into the compiler 
warnings database. 



4.2 The Debugger 

Some errors during execution automatically invoke the Lisp Machine's Debugger. You can 
enter the Debugger at other times by pressing c-m-SUSPEND. You can also enter the Debugger 
from within a program by inserting a call to dbg (with no arguments) into the code and 
recompiling. You can force a process into the Debugger by calling dbg with an argument of 
process. (See section 4.5, page 89.) 

The Debugger is useful for examining stack frames. With Debugger commands, you can see 
the arguments for the current stack frame, disassemble its code, return a value from it, go up 
and down the stack, and invoke the editor to edit function deOnitions. A common Debugger 
sequence is to disassemble code for the current frame, call the editor to edit and recompile the 
fimction, and test the changed function. 

A window-oriented version of the Debugger is the Display Debugger. Invoke it from within 
the Debugger by pressing c-«-U. 



Example 

We use the variable *z2* in computing the thickness of each stripe. *x2* is 
the x-coordinate of the projection of the last stripe in each arrow onto the 
top edge. We must bind it for each arrow to the difference between the 
value of *pOz* and twice the value of ^top-cdge<. 

Suppose that we forget to bind 'xl* for the big arrow in the function 
draw-blg-arrow. The initial value of *x2^ is nil. In the function 
coapote-dens, we subtract ^pOx* from *x2*. Because the value of *x2* is 
not a number, we generate an error when we Hrst call the function. The 
error invokes the Debugger with the name of the function in which the 
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error occurred, the value of the function's arguments, and the following 
error message: 

»Trap: The first argument given to SYS:— INTERNAL, NIL. was not a number. 

The Debugger also displays a listing of proceed types, special commands, and 
restart handlers, along with their key bindings (see Signalling and Handling 
Conditions, section 10.5, page 41). We can use one of these options, or we 
can use other Debugger commands to examine or manipulate the stack. 
Lefs use c-n-U to invoke the Display Debugger. 

Figure 6 (page 76) shows the Display Debugger frame as it looks when we 
invoke it. The top window, an inspect pane, shows disassembled code for 
conpate-dens with an arrow at the instruction that produced the error. 
The next window is an inspect history pane. The two windows side by side 
show the function's arguments and local variables and their values. The 
next window is a backtrace of the stack with an arrow at the frame that 
produced the error. The next window is a mouse-sensitive listing of options 
for proceeding or restarting. Next is a command menu. The bottom 
window is a Lisp Listener with the error message displayed. 

The disassembled code for compate-dens shows that the first argument to 
the subtraction that caused the error was the value of *x2*. We can 
inspect *x2* simply by cUcking on its printed representation in the 
disassembled code. Figure 7 (page 77) shows the Display Debugger after we 
inspect *x2*. The value of *z2* is nil. We could have confirmed this by 
evaluating 'xZ* in the Lisp Listener pane. 

Now, if we remember what the value of *x2* is supposed to be, we can set 
*x2* to that value by typing to the Lisp Listener pane: 

(setq *xZ* (- 'pOx* *top-edge* «top-edge*)) 

We can then click on [Retry] to reinvoke the stack frame and continue the 
program. 

If we forget the value of *x2*, we might want to look at the source code. 
We can invoke the editor by clicking on [Edit] and then on the name of the 
function we want to edit. Inside the editor, we can change and recompile 
code. We can edit draw-big-arrow to bind •x2* and then recompile that 
function. If we entered the Debugger from the editor, we cannot return to 
the Debugger, but we can run the program again. Otherwise, we can return 
to the Display Debugger by pressing c-Z. We can then set the value of 
*x2* and reinvoke the frame. 

In the Debugger, C-4CLP displays information on Debugger commands. Following are some of 
the most useful commands: 
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Reference 

c-fi 

c-E 

c-L 

c-N 
c-P 
c-R 
m-B 
nrL 

C""Bl""R 



Shows arguments for the current stack frame. 

Calls the editor to edit the function from the current 
frame. 

Clears the screen and redisplays the original error 
message. 

Goes down the stack by one frame. 

Goes up the stack by one frame. 

Returns a value from the current frame. 

Shows a backtrace of function names with arguments. 

Shows local variables and disassembled code for the 
current frame. 

Reinvokes the current frame. 

Invokes the Display Debugger. 



4.3 Commenting Out Code 

Sometimes a program runs but behaves in an unexpected way. In looking for the source of the 
problem, you might want to execute some portions of the program and disable others. An easy 
way to disable code without destroying it is to make a comment of it. You can comment out 
code by preceding it with a semicolon or surrounding it with #| and |#. 

Example 

We have outlined the large arrow and the largest of the small arrows. We 
try to outline the rest of the small arrows by adding two recursive function 
calls to do-arrows: 
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MW€ ffteM 



COMPUTE-DENS 

3 PUSH-INDIRECT «D1« 

4 BUILTIN —INTERNfiL STACK 

5 PUSH-LOCm. FP|e 

6 PUSH-INDIRECT »PeX< 

7 BUILTIN —INT ERNAL STACK 
18 PUSH-INDIRECT gRgi^ 

11 PUSH-INDIRECT «PeX^ 

12 BUILTIN —INTERNAL STACK 

13 BUILTIN FLOAT STACK 

14 BUILTIN /-INTERNAL STACK 



iX 



Mortbtlcm 



»<Stack-Frane COMPUTE-DENS PC-12> 



Args: 

Arg (H): 



1880 



Locals: 



(DO-ARROU) 

(0RAU-ARR0U-6RAPHIC 1288 1888 1888) 
(DRAU-BI6-ARR0U) 
(8TRIPE-ARR0UHEAD) 
(CONPUTE-NLINES 1888) 
»( COMPUTE-DENS 1888) 



Mcr* tf 69M 



JIf or* Mew 



Return to nornal debugser, staying In error context. 

Supply replacenent argunent 

Return a value fron the — INTERNAL Instruction 

Retry the —INTERNAL instruction 

Lisp Top Level In Lisp Listener 1 



What Error 
flrglist 



Inspect 
Edit 



Return 
ThroM 



"Set 



arg 
Search 



Retry 



1^ 
NIL 



>Trap: The first argunent given to SYS:— INTERNAL, NIL, uas not a nunber. 



jJl**25*«2 yS'lf? 5SJ Po«"*ln9 at the value. Right gets object Into error handler. 
88/28/83 17:81:23 ron GRAPHICS: Tyi 



Figure 6. The Display Debugger: inspecting the stack frame containing a call to 
coMpote-deDS. 
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Value is NIL 

plwrtj nst?'*(DOCUnENTflTION "...' SPECIAL «<U«IK-PflTHMflnE "yixofj /•des5/^workstyles« 
Package: «<Packa9e GRAPHICS 36$35277> 



Rrl 8 (X)x 1880 



Bottom ofobjtct 



' tt<Stack-Frane COHPUTE-DENS PCsl2> 
SK2« 



Locals: 



Mort ebo9t 



(DO-flRROU) 

(DRflU-RRROU-GRflPHIC 1288 1888 1888) 
(DRRU-BIG-RRROU) 
(STRIPE-flRROHHEflD) 
(COtlPUTE-NLINES 1888) 
^(COMPUTE-DENS 1888) 



ilfOK btlow 



Return to noma I debugger, staying In error context, 

Supply replacenent argument 

Return a value fron the — INTERNAL instruction 

Retry the —INTERNAL Instruction 

Lisp Top Level in Lisp Listener 1 



What Error 
flralist 



Inspect 
Edit 



Return 
Throw 



Set arg 
Search 



Retry 



"T" 

MIL 



>>Trap: The first argument given to SYS:— INTERNAL, NIL, uas not a nunber. 



Choose a value bs 
88/28/83 17:82:8! 



pointing at 
ron 



the value. Right gets object into 
GRAPHICS: Tyi 



hand 1 1 



Figure 7. The Display Debugger: inspecting the variable *x2*. 
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(defun do-arrows () 

;; Don*t exceed maxlmura recursion level 
(when (< •depth* •max-depth*) 

;; Bind values for half and one-fourth of top edge 
(let ((nop-edge-2* (// *top-edge* 2)) 
(«top-edge-4« (// «top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 

;; Increment depth. Divide top edge In half. Bind new 
; ; coordinates for top right point of next arrow, 
(let (('depth* (U «depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (♦ *top-edge-4* (- *pOx* *top-edge*))) 
(*pOy* (- *pOy* *top-edge-2*))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow, 
(let ((*depth* (!♦ *depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx« (- 'pOx* *top-edge-2*)) 
(•pOy* (♦ *top-edge-4* (- •pOy* *top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 



This code produces the result shown in figure 8 (page 81). Something is 
clearly wrong with at least one of the function calls, but the complexity of 
the figure makes it difficult to see the source of the error. We simplify the 
figure by making a comment of the second recursive function call: 
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(defun do-arrows () 

;; Don*t exceed ■axlnun recursion level 
(vfhen (< *depth* *4iiax°depth*) 

;; Bind values for half and one-fourth of top edge 
(let ((nop-edge-Z* (// 'top-edge* 2)) 
(•top-edge-4* (// 'top-edge* 4))) 
(draw-arrow) ;Draw a snail arrow 

;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow, 
(let ((*depth* {\* *depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (♦ *top-edge-4* (- *pOx* *top-edge*))) 
(*pOy* (- *pOy* *top-edge-2*))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; IncrMwnt depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow. 



#1 



(let ((*depth* {I* *depth*)) 

(*top-edge* *top-edge-2*) 

(*pOx* (- *pOx* *top-edge-2*)) 

(*pOy* (♦ *top-edge-4* (- «pOy* *top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 



))) 



We recompile do-arrows (using c-sh-C), run the program again, and obtain 
the results shown in figure 9 (page 82). The small arrows now appear to be 
the right size, and the nimiber of recursion leveb is correct The problem 
seems to lie in the positioning of the arrows, or the calculation of the new 
values for *pOx* and *pOy*. On close inspection, we see that the x- 
coordinates look correct, but the y-coordinates are wrong. Instead of 
obtaining the new value of •pOy* by subtracting •top-edge-2* from the old 
♦pOy*, we should subtract •top-edge-4* from •pOy*. We change the 
definition of do-arrows: 
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(defun do-arrows () 



(let ((•depth* (l-i- *depth*)) 

(•top-edge* *top-edge-2*) 

(*pOx* (♦ *top-edge-4* (- *pOx* *top-edge*))) 
(«pOy* (- *pOy* *top-edge-4*)}) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow. 



#1 



(let ((*depth* (l-i- *depth*)) 

(*top-edge* *top-edge-2*) 
(•pOx* (- *pOx* *top-edge-2*)) 
(•pOy* (♦ *top-edge-4* (- *pOy* *top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 



l# 
))) 



When we recompile do-arrows and run the program again, we obtain the 
results shown in figure 10 (page 83). The first recursive function call is 
now correct Looking at the arguments in the second function call, we see 
that the same error exists in the calculation of the new *pOx*: We should 
subtract *top-edge-4*, not *top-cdge-2*, from the old *pOx*. We make 
the change, remove the #| and |#, and recompile do-arrows. We obtain 
the results shown in figure 1 (page 18). 

Example 

Figure 4 (page 59) shows a split screen, with graphic output in the upper 
window and source code in the lower. To adjust the size of the graphic for 
the smaller window, we have to change the arguments to 
draw-arrow-graphic when we call that function from do-arrow. We want 
to keep a record of the arguments we use to produce a full-screen figure. 
We can make a comment of the call to draw-arrow-graphic that uses full- 
screen arguments: 

(defun do-arrow () 

(setq *dest* (nake-lnstance *screen-arrow-output)) 

(send termlnal-lo *: clear -screen) 
; (draw-arrow-graphic 1280 1800 1800)) 

(draw-arrow-graphic 640 1300 1800)) 
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08/16/83 18:59^:51 ron 



Figure 8. Output resulting from a faulty attempt to outline the small arrows recursively. 



82 
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15RHPHICS; Tvl 



Figure 9. Output resulting from a faulty attempt to outline the small arrows recursively, with 
the second function call commented out. 
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B8/l6/'83 19:95:25 ron 



Figure 10. Output resulting from a corrected attempt to outline the small arrows recursively, 
with the second function call commented out. 
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4.4 Tracing and Stepping 



4.4.1 Tracing 



When a program runs but behaves unexpectedly, you might be calling 
functions in the wrong sequence or passing incorrect arguments. Tracing 
fimction calls can help detect this sort of problem. By default, tracing 
prints a message, indented according to the level of recursion, on entering 
and leaving a function. It also prints the arguments passed and the values 
returned. 

You can invoke tracing in three ways: 

Click on [Trace] in the system menu 
Use Trace (n-X) in Zmacs 
Use the trace special form 

[Trace] and Trace (m-X) pop up a menu of options, including stepping and 
inserting breakpoints. You can use these options with trace, too, but the 
syntax is complex. Table 1 (page 87) summarizes the correspondence 
between trace menu items and trace options. See the Lisp Machine Manual^ 
section 26.3, page 457, for a description of the options. 

Example 

Suppose that we had begim writing the recursive function calls in do-arrows 
with the following code, passing arguments to do-arrows instead of binding 
the special variables: 

(defun draw-arrow-graphic (•top-edge* 'pOx* •pOy*) 



(draw-big-arrow) 

(do-arrows nop-edge-Z* (- "pOx* *top-edge-2*) (- 'pOy* •top-edge-2*))) 
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(defun do-arrows ("depth* *top-edge* "pOx* *pOy«) 
;; Don*t exceed naxlnum recursion level 
(when (< «depth* *max-depth*) 

;; Bind new values for half and one-fourth of top edge 
(let ((nop-edge-Z* (// «top-edge« 2)) 
(•top-edge-4« (// nop-edge* 4))) 
;; Draw a soiall arrow 
(draw-arrow) 

;; Draw a left-hand child arrow, dividing top edge In half, 
;; Incrementing depth, and passing new coordinates for top 
;; right point 
(do-arrows "top-edge-Z* (1* 'depth*) 

(+ «top-edge-4* (- 'pOx* *top-edge*)) 
(- *pOy* *top-edge-4*)) 
;; Draw a right-hand child arrow, dividing top edge In half, 
;; Incrementing depth, and passing new coordinates for top 
;; right point 

(do-arrows *top-edge-2* (1+ *depth*) (- *pOx* •top-edge-4*) 
(♦ *top-edge-4* (- *pOy* *top-edge*)))))) 

This code produces only the first of the small arrows. Again, something 
appears to be wrong with the recursive fimction calls. Using Trace (n-X), 
we trace calls to do-arrows. We run the program again, and the following 
trace output appears: 

(1 ENTER DO- ARROWS (0 640 1160 1160)) 

(2 ENTER DO-ARROWS (320 1 680 1000)) 

(2 EXIT DO-ARROWS NIL) 

(2 ENTER DO-ARROWS (320 1 1000 680)) 

(2 EXIT DO-ARROWS NIL) 
(1 EXIT DO-ARROWS NIL) 
NIL 



The problem here is immediately apparent: The order of the first two 
arguments in the recursive fimction caUs is reversed. We are passing the 
new value of *top-edge* as the new value of *depth* Because this value 
exceeds that of *Baz-depth*, the function returns after the first recursive 
call 



Reference 

Trace (n-X) Traces or untraces a specified 

function. Prompts for the name of a 
function to trace and pops up a menu 
of trace options. 

[Trace] (from a system menu) Traces or untraces a spedfled 

function. Prompts for the name of a 
function to trace and pops up a menu 
of trace options. 
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4.4.2 Stepping 



(trace (tfonctJon function-spec- 1 ovtion-1 option-2 ...) ^^ 

Enables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword :f anction is 
unnecessary. An argument can also 
be a l^t whose car is a list of 
function names and whose cdr is one 
or more options. In this case, all 
functions in the list are traced with 
the same options. With no 
arguments, returns a list of functions 
being traced. 

(antrace dfnpctlon function-spec- D ^ 

IKsables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword ifonction is 
unnecessary. With no arguments, 
untraces all functions being traced. 



When a program behaves unexpectedly and tracing doesn't reveal the 
problem, you might step through the evaluation of a function call You can 
step through function execution by using step, [Step] from a trace menu, ot 
the :step option to trace. 

You can step through the executicm ci a function only if it is interpreted, 
not compiled. If you want to step through execution of a compile 
function, read the definition into a Zmacs buffer and use a Zmacs command 
(such as c-sh-E) to evaluate it (see section 3.2.1, page 66). 

The Stepper prints a partial representation of each form evaluated and the 
values return^. A back arrow («-) precedes the representation of each form 
being evaluated. A double arrow (•) precedes macro forms. A forward 
arrow (-») precedes returned values. 

After printing, the Stepper waits for a command before proceeding to the 
next step. Stepper commands allow you to specify the level of evaluation to 
be stepped, escape to the editor, or enter a Lisp breakpoint loop. Press 
HELP inside the Stepper or see the Lisp Machine Manual, section 26.5, 
page 464, for a list of commands. Following are some basic Stepper 
commands: 

Command Action 

c-N Evaluate until next thing to print 

SPf)CE Evaluate until next thing to print at this level (don*t step 

at lower levels) 
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Table 1. Trace Menu Items and trace Options 
Trace menu item trace option 

[Cond break before] :break predicate 



[Break before] 


:break t 


[Cond break after] 


:exitbreak predicate 


[Break after] 


:ezitbreak t 


[Error] 


terror 


[Step] 


»tep 


[Cond before] 


:entrycond predicate 


[Cond after] 


:exitcond predicate 


[Conditional] 


:cond predicate 


[Print before] 


:entryprint form 


[Print after] 


rexitprint form 


[Print] 


:print form 


[ARGPDL] 


uffgpdl pdl 


[Wherein] 


:wherein function 


[Untrace] 






tentry list 




:exit list 



uu'g :Talae :both mil 



Description 

Enters breakpoint on function entry 
if predicate not nil 

Enters breakpoint on function entry 

Enters breakpoint on function exit 
if predicate not nil 

Enters breakpoint on function exit 

Enters Debugger on function entry 

Steps through (interpreted) function 
execution (see section 4.4.2, page 86) 

Prints trace output on function 
entry if predicate not nil 

Prints trace output on function 
exit if predicate not nil 

Prints trace output on function 
entry and exit if predicate not nil 

Prints value of form 
in trace entry output 

Prints value of form 
in trace exit output 

Prints value of form in 
trace entry and exit output 

On function entry, pushes list 
of function name and args onto 
pdl\ pops list on function exit 

Traces function only when 
called within function 

Calls ontrace on function 

Prints values of forms in 
list on function entry 

Prints values of forms in 
list on function exit 

Controls printing of args 
on function entry and values 
on function exit 
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c-U Evaluate until next thing to print at next level up (don't 

step at current and lower levels) 

c-B Enter breakpoint loop 

c-E Enter Zmacs 

c-X Evaluate until finished (exit from stepping) 



Example 

We have the same problem with the function do-arrows as we described in 
section 4.4.1 (page 84). The program outlines only the largest of the small 
arrows, indicating a problem with the recursive function caUs. Instead of 
just tracing do-arrows, we step through its evaluation. We first use c-sh-E 
to evaluate the definition of do-arrows. We then use [Step] in the menu 
that Trace (n-'X) pops up to trace and step through do-arrows. We run 
the program. The Stepper waits for a command before evaluating each 
form in do-arrows. We press SPf)CE to skip to the next form at the same 
level. When we come to the comparison of *depth* and *max-depth* in 
the recursive calls, we want to see each level of evaluation. We press c-N 
at each of these steps. The tracing and stepping output looks as follows: 

(1 ENTER DO- ARROWS (0 640 1160 1160)) 

• (WHEN « "DEPTH* •HAX-DEPTH*) (LET (('TOP-EDGE-Z* (// "TOP-EDGE* 
«" (COND (« "DEPTH* «MAX-DEPTH*) (PROGH (LET ((*T0P-EDGE-2* (// *T 

(2 ENTER DO- ARROWS (320 1 680 1000)) 

• (WHEN « *DEPTH* "HAX-DEPTH*) (LET ((*T0P-EDGE-2* (// *TOP-EDGE« 
«- (COND (« *DEPTH* •MAX-DEPTH*) (PROGN (LET ((*T0P-EDGE-2* (// *T 

«- « "DEPTH* *KAX-DEPTH*) 

•• 'DEPTH* -• 320 

«■ *MAX-DEPTH* -» 7 
«- « *DEPTH* *MAX-DEPTH*) ■» NIL 
*■ (COND (« *DEPTH* *MAX-DEPTH*) (PROGN (LET ((*T0P-EDGE-2* (// *T -» NIL 
(2 EXIT DO- ARROWS NIL) 
(2 ENTER DO-ARROWS (320 1 1000 680)) 

• (WHEN « *DEPTH* *MAX-DEPTH*) (LET ((*T0P-EDGE-2* (// *TOP-EDGE* 
•• (COND (« *DEPTH* *MAX-DEPTH*) (PROGN (LET ((*T0P-EDGE-2* (// *T 

«- (< *DEPTH* *MAX-DEPTH*) 
«■ *DEPTH* -» 320 
•■ *MAX-DEPTH* •• 7 
•- « "DEPTH* "MAX-DEPTH") ■» NIL 
«■ (COND (« "DEPTH" "MAX-DEPTH") (PROGN (LET (("TOP-EDGE-2" (// "T -» NIL 

(2 EXIT DO-ARROWS NIL) 
(1 EXIT DO- ARROWS NIL) 
NIL 



In this example, stepping shows even more clearly than tracing that the 
value of *depth* is wrong in the recursive function calls. 
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Reference 

(step form) Steps through the evaluation of form 

Trace (m-X) [Step] Steps through the execution of a 

function being traced. 

[Trace / Step] (from a system menu) Steps through the execution of a 

function being traced. 

(trace (:f nnction function-spec :step» 

Steps through the execution of a 
function being traced. If 
function-spec is a symbol, the keyword 
:f unction is imnecessary. 

4.5 Breakpoints 

In debugging a program, you might want to interrupt function execution to enter a Lisp 
breakpoint loop or the Debugger. Entering the Debugger is usually more useful, for there you 
can examine the stack, return values, and take other steps in addition to evaluating forms. 

You can use two general kinds of breakpoints: 

• You can edit into a definition a call to dbg (with no arguments) or to 
break. The advantage of this kind of breakpoint is that, as with stepping, 
you can interrupt execution within the function. The disadvantage is that 
you have to edit and recompile the deHnition to insert and remove the 
breakpoint If you redeHne the fimction after inserting the breakpoint, the 
breakpoint might be lost. 

• You can use breakon or one of the error or break options to trace. These 
features create encapsulations, functions that contain the basic definitions of 
the functions to which you want to add breakpoints (see the Lisp Machine 
Manual, section 10.10, page 153, for more on encapsulations). The 
advantage of this kind of breakpoint is that when you recompile or 
otherwise redefine the fimction, only the basic definition is replaced, and the 
breakpoints remain. The disadvantage is that you can interrupt fimction 
execution only on entry or exit, not within the function. 

You insert these breakpoints by calling breakon or trace from a Lisp 
Listener or by using the trace menu; you remove them by calling 
onbreakon or ontrace. When you break on entering function execution, 
just before applying the function to its arguments, the variable arglist is 
bound to a list of die arguments. When you break on exiting from function 
execution, just before the function returns, the variable valoes is bound to a 
list of the returned values. 

From either a breakpoint loop or the Debugger, RESUME allows the program to continue, and 
RBORT returns control to the previous break or, if none exists, to top level. 
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Example 

We decide to break on entry to do-arrows and enter the Debugger while 
tracing the function. We use Trace (m-X) and then [Error] from the trace 
menu. We select a Lisp Listener and run the program. On the first entry 
to do-arrows we enter the Debugger, with the following message: 

» TRACE Break: DO-ARROWS entered. 

DO- ARROWS: (encapsulated for TRACE) 

Rest arg (ARGLIST): (0 640 1160 1160) 
s-R, F£9JltE: Proceed without any special action 
S-B, fSORT: Lisp Top Level In Lisp Listener 1 



Reference 
(dbg£r2£^ 



Enters the Debugger in process. With 
an argument of t, finds a process that 
has sent an error notiflcation. With 
no argument, enters the Debugger as 
if an error had occurred in the 
current process. 



(break tgg conditional- form') 



Enters a Lisp breakpoint loop 
(identified as "breakpoint t(^) if 
conditional-form is not nil or is not 
supplied. 

(breakon function-spec conditional- formS 

Passes control to the Debugger on 
entering function-spec if 
conditional-form is not nil or b not 
supplied. With no arguments, returns 
a list of functions with breakpoints 
specified by breakon. 

(nnbreakon function-svec conditional- form) 

Turns off the breakpoint condition 
specified by conditional-form for 
function-spa:. If conditional-form is 
not supplied, turns off all breakpoints 
specified by breakon for 
function-spec. With no arguments, 
turns off all breakpoints specified by 
breakon for all functions. 



[Error] (from a trace menu) 



Passes control to the Debugger on 
entering a function being traced. 
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[Cond break before] (from a trace menu) 

Prompts for a predicate. Displays 
trace entry information and enters a 
Lisp breakpoint loop on entering a 
function being traced if the predicate 
is not nil. 

[Cond break after] (from a trace menu) 

Prompts for a predicate. Displays 
trace exit information and enters a 
Lisp breakpdnt loop on exiting from 
a function being traced if the 
predicate is not nU. 

(trace (:f onction function-spec :error)) 

Passes control to the Debugger on 
entering a function being traced. If 
function-spec is a symbol, the keyword 
:f onction is unnecessary. 

(trace (:f onction function-spec :break predicatify 

Prints trace entry information and, if 
the value of predicate is not nil, 
enters a Lisp break loop on entering 
the function. If function-spec is a 
symbol, the keyword :f onction is 
unnecessary. 

(trace (:f onction function-spec :exitbreak predicati^ 

Printe trace exit infommtion and, if 
the value of predicate is not nil, 
enters a Lisp break loop on exiting 
from the function. If function-spec is 
a symbol, the keyword :f onction is 
unnecessary. 

4.6 Expanding Macros 

Sometimes a program bug appears to stem from unexpected behavior by a macro. Seeing how 
a macro form expands can help find the bug. To be sure that a macro does what you want it 
to, you might also want to create and expand a macro form soon after defining the macro and 
compiling the definition. 

You can expand a macro form in a Zmacs buffer using Macro Expand Expression (c-sh-M). 
This command expands the form following point, but not any macro forms within it To 
expand all subforms, use Macro Expand Expression All (m-X). You can also expand macro 
forms with mexp, which enters a loop to read and expand one form after another. 

Example 

We have just written code to stripe the shafts of the small arrows, drawing 
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stripes with uniform spacing and density. We produce the results shown in 
figure 11 (page 93). We evidently have a problem with the function 
draw-arrow-shaft-stripes. The code for this function is as follows: 

(defun draw-arrow-shaft-stripes 

(left-x top-y right-x bottom-y) 
;; Find y-coord of starting point of stripe. Don*t go 
;; below the bottom of the triangle. 

(loop for start-y from top-y by 'stripe-distance* above bottcm-y 
;; Find x-coord of ending point of the stripe 
for end-x from rIght-x by «str1pe-d1 stance* 
;; Draw a stripe 
do { draw-arrow-shaft- lines 

left-x start-y end-x bottom-y))) 

The bug stems from incorrect coordinates for the endpoints of the shaft 
stripes. The beginning coordinates (left-x and start-y) are correct. The 
ending y-coordinate (bottom-y) looks right, but the ending x-coordinate 
(end-x) is wrong. The problem might not be evident from looking at the 
code, which consists entirely of a loop form. We move to the beginning of 
the loop form and expand it, using c-sh-M: 

((LANBDA (START-Y G1049 G1050) 
((LAMBDA (END-X G1051) 
(PROG NIL 

(AND (NOT (GREATERP START-Y 61050)) (GO SI:END-LOOP)) 
SI: NEXT- LOOP 

(DRAU-ARROW-SHAFT-LINES LEFT-X START-Y ENO-X BOTTOM-Y) 
(SETO START-Y (DIFFERENCE START-Y G1049)) 
(AND (NOT (GREATERP START-Y G1050)) (GO SI:END-LOOP)) 
(SETQ END-X (PLUS END-X G1051)) 
(GO SI: NEXT- LOOP) 
SI: END-LOOP 

)) 

RIGHT-X 

*STRIPE-DISTANCE*)) 
TOP-Y 

•STRIPE-DISTANCE* 
BOTTOM-Y) 

The expansion shows the lambda-bindings and prog form that the loop 
macro creates. We can see that the error is in the setting of end-x within 
the prog form: We are incrementing end-x by •stripe-distance*, when we 
should be decrementing it. The problem is in our use of a loop keyword. 
Instead of virriting 

for end-x from rIght-x by *str1pe-d1stance* 
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MIL 




Lisp Listener 1 



Uij/lb<^u3 19:09:13 ron 



GRHPHICS: Tyl. 



Figure 11. Output from the program with a bug in the function 
draw-arrow-shaft-stripes. 
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we should have written 

for end-x dovmfrom right-x by *str1pe-d1 stance* 

We make the change and recompile draw-trrow-shaf t-strlpes. Now if we 
expand the loop form, we see that we are decrementing end-x: 

((LAMBDA (START-Y 61062 61063) 
((LAMBDA (END-X G1064) 
(PROG NIL 

(AND (NOT (GREATERP START-Y G1063)) (GO SI: END- LOOP)) 
SI: NEXT-LOOP 

(DRAW-ARROW-SHAFT-LINES LEFT-X START-Y END-X BOTTOM-Y) 
(SETQ START-Y (DIFFERENCE START-Y 61062)) 
(AND (NOT (GREATERP START-Y 61063)) (60 SI:END-LOOP)) 
(SETQ END-X (DIFFERENCE END-X 61064)) 
(GO SI:NEXT-LOOP) 
SI: END-LOOP 

)) 

RIGHT-X 

•STRIPE-DISTANCE*)) 
TOP-Y 

*STRIPE-DISTANCE* 
BOTTOM-Y) 



Reference 

Macro Expand Expression (c-sh-M) 



Macro Expand Expression All (m-X) 



(mexp) 



Expands the macro form following 
point. Does not expand subforms 
within the form. 

Expands the macro form following 
point and all subforms within the 
form. 

Enters a loop: prompts for a macro 
form to expand, expands it, and 
prompts for another macro form. 
Exits from the loop on nil. 



4.7 The Inspector 

The Inspector is a window-based tool that combines the describe and disassemble functions. 
Invoke it with inspect, SELECT I, or [Inspect] from a system menu. If you use inspect, the 
Inspector is not a separate activity from the Lisp Listener in which you invoke it. In that case 
you cannot use SELECT L to return to the Lisp Listener; you must click on [Exit] or [Return] 
in the Inspector menu. 
The Inspector displays information about an object and lets you modify the object. It displays 
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information for the last object inspected in the bottom window. It displays information for the 
two previous objects in the windows above the bottom one. It maintains a mouse-sensitive 
listing of all inspected objects in the history window. These are some of its useful features: 

• The information the Inspector displays depends on the object's type. For a 
symbol, it displays a representation of the value, function, property list, and 
package. For a symbol's flavor property, it displays information about 
instance variables, component and dependent flavors, the message handlM", 
init keywords, and the flavor property list. For a compiled function, it 
displays the disassembled assembly-language code that represents the 
compiler output. 

• The Inspector is especially usefiil for examining data structures. It displays 
the names and values of the slots of structures and, unlike describe, the 
elements of (one-dimensional) arrays. For instances of flavors, the Inspector 
displays the names and values of instance variables. 

• Within each display, most representations of objects are mouse sensitive. If 
you click on an object representation, you inspect that object. For example, 
you can inspect elements of lists. If an element of an array is itself an 
array, you can inspect the second array. In this way you can follow long 
paths in data structures. 

• You can change a value by using the [Modify] option in tbe Impector's 
menu. You can return a value when you exit the Inspector by clicking on 
[Return]. 

Sec Operating the Lisp Machine, chapter 5, page 28, for more on the Inspector. 

Example 

Suppose we had represented each arrow as an instance of a structure 
(defined with def struct) instead of a collection of special-variable values. 
We could have called the structure representing the small arrows arrow and 
set the value of a special variable, *arr*, to each instance of the structure as 
we created it. 

Figure 12 (page 96) shows an Inspector window for the last arrow in the 
figure. We first run the program in a Lisp Listener, then invoke the 
Inspector using SELECT I. Because we typed (pkg-goto ^graphics) in the 
Lisp Listener, the Inspector's package is graphics. We type *arr* to the 
interaction pane at the top of the frame. The window at the bottom of the 
frame displays the names and values of the structure slots. We can change 
these values by using the [Modify] menu option. 

Example 

Suppose we had represented each arrow as an instance of a flavor and 
defined most of our computation ftmctions as flavor methods instead of 
simple functions. We could have called the flavor representing the small 
arrows arrow and set the value of 'arr* to each instance of the flavor as 
we created it. 
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Figure 12. The Inspector window: inspecting an instance of a structtire. 
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Figure 13 (page 98) shows an Inspector window for the last arrow in the 
figure. As with our structure example, we first run the program and then 
invoke the Inspector to evaluate •arr* and inspect the flavor instance that is 
its value. The Inspector displays the names and values of instance variables 
and a representation of the flavor's message handler. 

We next cUck on the mouse-sensitive representation of the message handler. 
The Inspector displays a representation of the function spec for the method 
that handles each message. If we click on the function spec for the 
:compiite-dens method for flavor basic-arrow, the Inspector displays the 
method's disassembled code. 



Reference 
(inspect obJKt) 

SELECT I 

[Inspect] (from a system menu) 

(disassemble function) 

Disassemble (m-X) 



Selects an Inspector window in which 
to inspect object. 

Selects an Inspector window. 

Selects an Inspector window. 

Prints a repr^entation of the 
assembly-language instructions for a 
compiled function. 

Prompts for the name of a compiled 
function and displays a representation 
of the function's assembly-language 
instructions. 
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Figure 13. The Inspector window: inspecting an instance of a flavor. 
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Figure 13, continued. 
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5. Using Flavors and Windows 

All Lisp Machine Lisp programmers must know how to use flavors and the window system in 
at least an elementary way. Flavors are the basis of a powerful, nonhierarchical kind of objKt- 
oriented programming. Even if you don't use them extensively, the system code does. 
Applications that include screen display or user interaction must deal with the window system, 
which is itself built on flavors. 

In this chapter we present a brief introduction to using flavors and windows. We do not 
discuss the concepts and organization of flavors and the window system in any detail. Instead, 
we modify the output module of our example program to show some simple uses of flavors, 
windows, and menus. We show basic examples of the following features: 

• Using base, mixin, and instantiable flavors and :daemon method 
combination 

• Creating a simple window and associating it with a process 

• Producing LGP output 

• Altering values iising a choose-variable-values window 

• Signalling a condition and proceeding 

We also present some editor commands and Lisp fimctions for finding information about 
flavors and windows. Among the issues we do not discuss in any detail are the following: 

• Using types of method combination other than :d«eiiion 

• Interacting with the mouse process 

• Creating frames 

• Specifying fonts 

• Using menus 

For more information on flavors and windows, read the following documents: 

• On flavors: Lisp Machine Manual, chapter 20, page 279 

• On windows: Introduction to Using the Window System 

• On menus: Lisp Machine Choice Facilities 

• On conditions and errors: Signalling and Handling Conditions 

5.1 Program Development: Modifying the Output Module 

As now written, the output routines of our example program consist of a flavor and methods 
that produce lines on the stream to which terminal-io is bound: 

(def flavor screen-arrow-output 
((scale-factor 2.5)) 
()) 
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(defnethod (screen-arrow-output :show-11nes) 
(x y &rest x-y-pairs) 
(loop for xO 3 (send self *:coinpute-x x) then xl 
for yO s (send self *:cofflpute-y y) then yl 
for (xl yl) on x-y-paIrs by #*cddr 
do (setq xl (send self *:compute-x xl) 
yl.(send self 'zcoiqpute-y yl)) 
(send ternlnal-lo *:draw-11ne 

xO yO xl yl tv:a1u-1or t))) 

(def method (screen-arrow-output :compute-x) (x) 
(fixr (// x scale-factor))) 

(defnethod (screen-arrow-output :cofflpute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 

We want to be able to produce output on the screen, an LGP, or a file. For this we need a 
simple device-independent graphics system that uses generic operations. The central operation is 
:show-lines, which receives endpoint coordinates from the calculation module and produces 
lines on the approi^te output stream. Our general strategy for creating the output options is 
as follows: 

1. DeHne a flavor and methods to calculate the position of the arrow figure on 
the screen or page. We can use this mixin with flavors that produce any 
kind of output. 

2. Define flavors and methods to produce screen output. We build the 
instantiate flavors on t?:wlndow and instantiate them with 
t?:make-wlndow. We define two kinds of arrow window fbvors: 

• A basic flavor that performs output and redisplays the window after 
changes. 

• A flavor, which we instantiate, that is built on the basic window and 
includes a mixin to convert LGP coordinates to screen coordinates. 

3. Define a flavor and methods to produce LGP or file output 

4. Deflne a top-level function that uses a choose-variable-values window to 
select the type of output and alter some variables. The function calls 
tT:make-window or makes an instance of the LGP flavor, depending on the 
output type. 

5. Change the arrow-window flavors to allow multiple windows, associate each 
window with its own process, and allow the user to modify the 
characteristics of the flgure in each window. 

6. Deflne a function to check for mistakes when the user changes the values 
of variables. We define condition flavors for the incorrect choices. We 
deflne handlers for the conditions and use signal to signal them. We allow 
the user to proceed by supplying new values for the variables. 
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We want to preserve modularity in writing these new routines. We define the flavor that 
positions the arrow figure so that we can use it with any sort of output. We keep the 
operations that transform LGP to screen coordinates separate from the basic window 
operations. We define the routines that handle bad variable values as separate flavors and 
functions. These precautions make it easy to define new kinds of windows or to check for 
errors in other variable values in the future. 



5.1 .1 A Mixin to Position tlie Figure 

No matter what the output device, we want to be sure that the figure fits 
within the bounds of the page or window and is centered within the page or 
window. We define a mixin flavor, arrow-parameter-Dixin, with methods 
to perform these calculations. We include this flavor in all flavors that 
produce output for the figiue. 

We define five instance variables to hold the parameters. Three of these, 
top-edge, right-x, and top-y, are the arguments we must pass to the 
calculation module. We make these three instance variables gettabk so that 
we can retrieve them by sending messages to an instance of the dependent 
flavor. The other two instance variables are the width and height of the 
page or window in the appropriate units, either LGP or screen pixels. 

(defflavor arrow-parameter-mlxln 

(width height top-edge rIght-x top-y) 

() 
(:gettab1e-1nstance-var1ab1es top-edge r1ght-x top-y) 

( :docunentat1on :m1x1n 

"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure.")) 

The task of this flavcH- is to perform a generic operation, which we call 
tcompnte-parameters. This operation consists of separate computations for 
top-edge, right-x, and top-y. We define primary methods for these 
operations here, using coordinates with the origin at bottom left. Flavors 
that mix in this one can add daemons, whoppers, or their own primary 
methods to accommodate other coordinate systems and scale factors. 

We perform these operations as follows: 

1. Determine the width and height of the page or window. The details of this 
operation are the business of other flavon. We specify a required method, 
:compate-width-and-height, for any flavor that mixes in this one. We send 
celf a :compate-width-and-height message to set the instance variables. 

2. Calculate a provisional value for top-edge so that the figure fits within the 
smaller dimension of the page or window. We allow the user to specify, by 
setting the global variable *flll-proportlon*, what fracti(»i of this dimension 
the figure should fill. 
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3. Adjust the top edge so that its value is at least 128 and is a multiple of 128 
if larger. This adjustment ensures that stripe spacing is continuous 
throughout the levels of the figure. 

4. Calculate rlght-z and top-y so that we center the figure within the page or 
window. 

The complete code for this flavor and its methods is as follows: 

(defvar •fill-proportion* 0.9 
"Proportion of smaller dimension to be filled by figure*) 



(def flavor arrow-paraneter-nlxin 

(width height top-edge right-x top-y) 
() 

(:gettab1e-1nstance-var1ab1es top-edge rIght-x top-y) 

( : requ 1 red-methods : conpute-wl dth-and-he 1 gh t ) 

(: documentation :m1x1n 

"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering It within the page or window and making It fill no 
more than the specified proportion of the smaller dimension. 
The methods use a coordinate system with origin at bottom left; 
other mixins must correct for this if output Is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed Into any Instantlable flavor that produces output for the 
arrow graphic.*)) 

Nethod controlling calculation of size and position of figure. 
Sends messages to self to calculate width and height of page 
or window, length of top edge of figure, and coordinates of 
figure's top right point. These are separate methods so that 
other flavors can shadow them or add daemons. Another flavor 
must provide a method to compute width and heights because 
this Is specific to the output device, 
(defmethod (arrow-parameter-mlxin : compute-parameters) () 

;; Another flavor must supply method for width and height 

(send self *:compute-w1dth-and-he1ght) 

;; Hake a preliminary estimate of length of top edge 

(send self *: compute- top-edge) 

;; Adjust top edge to make It a multiple of 128 

(send self *: ad Just- top-edge) 

;; Calculate coordinates of top right point of figure. 

;; We can*t do this until we know how long top edge Is. 

(send self *:compute-r1ght-x) 

(send self *: compute- top-y)) 
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Makes a preliminary estimate of length of top edge. 
The top edge of the arrow Is 80 percent of the horizontal 
or vertical length of the tifhole figure. First finds the 
smaller of the length or width of the page or window. 
Multiplies this by the proportion of this dimension that 
Is to be filled by the figure. The result Is the 
horizontal or vertical length of the figure. Multiplies 
this by 0.8 to get the length of the top edge, 
(defmethod (arrow-parameter-mlxln : compute- top-edge) () 
(setq top-edge 

(fixr (« 0.8 *f111-proport1on* (min width height))))) 

; Adjusts length of top edge so It Is a multiple of 128. 
: There are 64 stripes In the head of the large arrow. The 
; calculation module divides the length of top edge by two 
; each time It goes down another recursion level. By making 
; the original top edge a multiple of 128, we maximize 
; continuity In striping between arrowheads and shafts and 
; among the first several levels of recursion, 
(defmethod (arrow-parameter-mlxln : ad Just- top-edge) () 
(setq top-edge 

;; Minimum length of top edge Is 128 
(If « top-edge 256) 128 

;; Otherwise set to next lower multiple of 128 
(• 128 (fix (// top-edge 128)))))) 



;; Calculates x-coordlnate of top right point of figure. 
;; Finds horizontal length of figure by dividing length of 
;; top edge by 0.8. Centers the figure horizontally within 
;; the page or window, 
(defmethod (arrow-parameter-mlxln :computo-r1i^t-x) () 
(setq right-x 

(fixr (• 0.5 (♦ width (// top-edge 0.8)))))) 



: Calculates y-coordlnate of top right point of figure. 
; Assumes that the origin is at bottom. Finds vertical 
: length of figure by dividing length of top edge by 0.8. 
: Centers the figure vertically within the page or window, 
(defmethod ( arrow-parameter -mixin : compute- top-y) () 
(setq top-y 

(fixr (• 0.5 (♦ height (// top-edge 0.8)))))) 



5.1 .2 The Basic Arrow Window 

We want to build our window on trnrlndow, a flavor that produces a 
simple window with bcvden^ a label, and graphics. Any arrow window we 
use must provide for initialization and redisplay, determine its width and 
height, and supply a :show-llnes method U> draw our figure. 

We define a mixin flavor, baslc-arrow-wlodow-inlxiii, with methods to do 
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these things. We require that this flavor be used with 
arrow-parameter-mixin and tir:window. For the basic window, we assume 
that the coordinates supplied to tshow-lines are screen coordinates, with 
origin at top left. 

We write basic-arrow-window-mixin as follows: 

1. Define the flavor. The :reqoired-flaTors option ensures that we have 
access to the flavors' instance variables and that an error will be signalled if 
someone makes an instance of a flavor that includes 
basic-arrow-wlndow-mixin but not the required flavors. The 
:defaalt-init-plist option provides values for some elements of the 
initialization property list in case no one else specifles them. The 
:edge$-froiD option with an argument of *:inoose alIo\^ the user to specify 
the initial size and position of the window by using mouse comers. We give 
an initial minimum width and height for the window because the length of 
top-edge must be at least 128, and we want the entire flgure to flt inside 
the window. 

(defflavor baslc-arrow-wlndow-mlxin () () 
(: required-flavors arrow-parameter-mlxln tv:w1ndow) 
(:defau1t-1n1t-p11st 
:edges-froni *:mouse :in1n1imjn-w1dth 200 :m1n1mum-he1ght 200 
:b11nker-p nil :expose-p t) 
( :docuroentat1on :m1x1n 

"Provides for a basic window to display the arrow graphic. 
ARROW- PARANETER-HIXIN Is needed to position the figure within 
the window. This flavor assumes window coordinates, with origin 
at top left.")) 

2. Provide a rshow-lines method to draw lines on the screen. We use 
essentially the same methods as in our original output module, but now we 
assume that the arguments are screen coordinates. We define separate 
:compate-x and :compate-y methods to transform the coordinates so that 
we can shadow these methods when we define another flavor to handle LGP 
coordinates. To produce the lines we use the :draw-Ilne method defined 
for tvigraphics-mixin, a component of tv:window. (In :daemoii method 
combination, when two component flavors have primary methods for the 
same message, the method of the flavor listed earlier in the component 
ordering shadows, or replaces, the method of the flavor listed later. For 
more on method combination, see the Lisp Machine Manuah section 20.12, 
page 306.) 
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Receives endpoint coordinates and draws lines on a window. 
Arguments are alternating x- and y-coordlnates of the end- 
points of lines to be drawn. If there are nore than two pairs 
of coordinates, assumes that the endpoint of one line Is the 
starting point of the next. Sends messages for separate methods 
to determine the actual coordinates. This is so that other 
flavors can nradlfy the coordinates. Draws a line by sending self 
a : DRAW-LINE message, and so assumes that TV:GRAPHICS-NIXIN Is 
Included somewhere to provide this method, 
(defmethod (baslc-arrow-wlndow-mlxin :show-11nes) 
(x y &rest x-y-pairs) 
First determine the starting point of the line. On 
subsequent trips through the loop, the last endpoint 
becomes the next starting point, 
(loop for xO s (send self *:compute-x x) then xl 
for yO s (send self *:compute-y y) then yl 
;; "Cddr" down the list created by making all but the 
;; first pair of coordinates an &rest. argument 
for (xl yl) on x-y-paIrs by #*cddr 
;; Determine the endpoint of the line 
do (setq xl (send self *:compute-x xl) 
yl (send self *:conn»ute-y yl)) 
;; Draw the line 
(send self *:draw-11ne 

xO yO xl yl tv:alu-1or t))) 



Determines the x-coordlnate of an endpoint of a line. 
This Is a separate method so that other flavors can shadow 
It or add daemons to manipulate the coordinate, 
(defmethod (baslc-arrow-wlndow-ralxin :compute-x) (x) 
(fixr X)) 



Determines the y-coordlnate of an endpoint of a line. 
Assumes that the argument already uses window coordinates, 
with origin at top left. This Is a separate method so that 
other flavors can shadow It or add daemons to manipulate 
the coordinate, 
(defmethod (baslc-arrow-window-mlxin :compute-y) (y) 
(fixr y)) 



3. Supply the :coinpate-width-and-height method required by 
arrow-parameter-Diixin. We use the :inside-size message to 
tviminimoni-window, a component of tT:window. We use muitiple-Talne 

to set the instance variables width and height. 



108 Program Development Tools and Techniques 

Symbolics, Inc. 



;;; Finds the Inside width and height of the window. 

;:; Sends self an :INSIDE-SIZE message, and so assumes that 

;;; TV:NINIMUM-WINDOW Is Included somewhere to provide this 

;;; method. 

(def method (baslc-arrow-wlndow-mlxin 

rcompute-wldth-and-helght) () 
(multiple-value (width height) 
(send self *: Inside-size))) 

4. Alter the computation of top-y to take account of the screen's origin at top 
left. We can do this in three ways: 

• Define a new primary method for :cofflpnte-top-y to shadow the method we 
defined for arrow-parameter-mixin. We would have to be careful to place 
basic-arrow-window-mixin before arrow-parameter-mixin in the list of 
component flavors for any flavor we wanted to instantiate. 

• Define :before and uifter daemons for :compDte-top-y. The :before 
daemon would make top-edge negative and the :after daemon would make 
it positive again. (In :daeraon method combination, :before methods for a 
message run before the primary method, and zafter methods run after the 
primary method. If two component flavors have daemons for the same 
message, the :bef ore method of the flavor listed earlier in the component 
ordering runs before the :bef ore method of the flavor listed later, and the 
:af ter method of the flavor listed earlier runs after the rafter method of 
the flavor listed later. For more on method combination, see the Lisp 
Machine Manual, section 20.12, page 306.) 

• Define a whopper for :compDte-top-y. This would do the same thing as the 
two daemons, except that when all the :compnte-top-y methods were 
combined it would run outside any daemons. (A whopper wraps the 
execution of some code around the execution of a method, running before 
all :before daemons and after all :after daemons. For more on whoppers, 
see the System 210 Release Notes, section 7.3, page 41.) 

We deHne a new primary method in this case because it repeats relatively 
httle code and makes the operation of the method clearer. If we used a 
whopper here, someone mig^t mix in another flavor with daemons that 
would unexpectedly run inside our whopper. 

;;; Calculates y-coordlnate of top right point of figure. 
;;; Finds vertical length of the figure by dividing the length 
;;; of top edge by 0.8. Centers the figure vertically within 
;;; the window. Gives the result In window coordinates, with 
;;: origin at top left. This method shadows that In 
:;: ARROW- PARAMETER-NIXIN. 

(defmethod (baslc-arrow-wlndow-mlxin : compute- top-y) () 
(setq top-y 

(fixr (• 0.5 (- height (// top-edge 0.8)))))) 
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. Calculate the figure's size and position and redisplay the window at 
appropriate times. We have to recompute the figure's size and position after 
the window is initialized and after its size or margins change. We have to 
redisplay the figure when the window is refreshed, but only if the window 
has no bit-save array or its size has changed. Before redisplaying, we have 
to clear the screen tf the window has a bit-save array. 
We perform these tasks by defining rafter daemons for three messages that 
the system can send to a window: dnlt, :change-of-$lze-or-marglns, and 
:refresh. You need daemons like these for most window-system 
applications. 

;;; Calculates size and position of figure after Initialization, 
(defmethod (baslc-arrow-wlndow-nlxln rafter :1n1t) (Ignore) 
(send self *: compute-parameters)) 

;;; Calculates size and position of figure after window change, 
(defmethod (baslc-arrow-wlndow-mlxin 

rafter :change-of-s1ze-or-marg1ns) (&rest Ignore) 
(send self *: compute-parameters)) 

;;; Draws the figure when necessary after window Is refreshed, 
(defmethod (baslc-arrow-wlndow-mlxin rafter rrefresh) 
(&opt1ona1 type) 
;; Draw figure If not restored from a bit-save array ... 
(when (or (not tvrrestored-blts-p) 

;; ... or size has changed, 
(eq type *r size-changed)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-b1ts-p 

(send self *rclear-screen)) 
;; Bind 'DEST* to self 
(let ((*dest« self)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 



We can now define a flavor of window, basic-arrow-window, built on our 
two mixin flavors and on tv:wlndow. The order of combination of flavors 
is important. We need to include basic-arrow-window-mixin before 
arrow-parameter-nixiii so that the :coinpiite-top-y method for 
basic-arrow-window-mixin shadows that for arrow-partmeter-mixin. We 
must also put basic-arrow-window-mixin before tv:window so that our 
uifter daemons will nm after any that tv:window or its components might 
provide. 
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(defflavor basic-arrow-window () 

(baslc-arrow-wlndow-rolxln 
arr ow-par ame t er-ml X 1 n 
tv: window) 
(: documentation :comb1nat1on 
"Instantlable flavor providing a basic window for output. 
Though this flavor is Instantlable, Its methods assume that 
point coordinates use the window coordinate system, with 
origin at top left. To work with the current calculation 
module It needs another mixin to convert LGP to screen 
coordinates. In the component flavors. BASIC-ARR(W-WINDOW-HIXIN 
must come before ARROW-PARAMETER-NIXIN and TV:WIN0OW for 
shadowing and daemons to work correctly.")) 



We can actually make an instance of this flavor. We deflne no new 
methods for it, leaving all methods to component flavors. If we had a 
calculation module that used screen coordinates, basic-arrow-window would 
be the right flavor to use for screen output. 



5.1 .3 Converting LGP to Screen Coordinates 

Because our calculation module uses LGP coordinates, we need another 
flavor of window to produce output. We deflne a flavor, 
Igp-window-mixin, to be mixed in with basic-arrow-window. We need a 
new instance variable, scale-factor, whose value is the ratio of LGP to 
screen pixel densities. 



(aefflavor Igp-wlndow-mlxin 
((scale-factor 2.5)) 
() 

( :requ1red-f lavors basic-arrow-window) 

(: documentation :m1x1n 
"Converts LGP to screen coordinates and vice versa. 
When mixed In with BASIC -ARROW- WINDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The Instance variable SCALE-FACTOR Is the 
ratio of LGP to screen pixel density. The methods take 
the height and width of the window In screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure In LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those In 
ARROW-PARAMETER-NIXIM and BASIC-ARROW-WINDOW-HIXIN . " ) ) 



We next define new primary methods to incorporate the scale factor into 
the calculation of top-edge, right-x, and top-y. These methods shadow 
those defined for arrow-parameter-mixin and basic-arrow-window-mixin. 
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;;; Calculates top edge In LGP pixels fron screen proportions. 
;;; Hultlplles length of smaller dinenslon. In screen pixels, by 
;;; proportion of this dimension to be filled by the figure. 
;;; Multiplies this by 0.8 to find top edge in screen pixels. 
;;; Corrects for higher density of LGP pixels. This method 
;;; shadows that of ARROW-PARAMETER-NIXIN. 
(defmethod (Igp-wlndow-mlxin : compute- top-edge) () 
(setq top-edge 

(fixr (• scale-factor 0.8 •fill -proportion* 
(min width height))))) 

;;; Calculates x-coord of top right point In LGP pixels. 
;;; Finds horizontal length of figure In screen pixels by 
;;; dividing top edge by 0.8. Centers figure horizontally 
;;; In window, correcting for higher density of LGP pixels. 
;;; This method shadows that of ARROW- PARAHETER-HIXIN. 
(defmethod (Igp-wlndow-mlxin :compute-r1ght-x) () 
(setq right-x 

(fixr (« 0.5 (♦ (• width scale-factor) 
(// top-edge 0.8)))))) 

;;; Calculates y-coord of top right point In LGP pixels. 
;;; Finds vertical length of figure In screen pixels by 
;;; dividing top edge by 0.8. Centers figure vertically 
;;; In window, correcting for higher density of LGP pixels. 
;;; This method shadows those of ARROW- PARANETER-NIXIN and 
;;; BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-wlndow-mlxin :compute-top-y) () 
(setq top-y 

(fixr (• 0.5 (♦ (* height scale-factor) 
(// top-edge 0.8)))))) 



Finally, we need to modify the coordinates used in the rshow-lines method 
to take accoimt of the scale factor and the difference in origins for LGP 
and screen coordinates. We define new methods for :compate-x and 
:compate-y to shadow the methods we defined for 
basic-arrow-window-mixin. 



;;; Converts x-coord of line endpoint from LGP to screen pixels. 
;;; Corrects for higher density of LGP pixels. This method shadows 
;;; that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-wlndow-mlxin :compute-x) (x) 
(fixr (// X scale-factor))) 

;;; Converts y-coord of line endpoint from LGP to screen pixels. 
;;; Corrects for higher density of LGP pixels and for screen origin 
;;; at top left. This method shadows that of BASIC-ARROW-WIMOOW-MIXIM. 
(defmethod (Igp-wlndow-mlxin :compute-y) (y) 
(fixr (- height (// y scale-factor)})) 
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Wc can now define the flavor we will actually instantiate with 
t¥:oiake-window. This flavor, arrow-window, is just a combination of 
Igp-window-mixin and basic-arrow-window. 



(defflavor arrow-window () 

( Igp-window-ralxin basic-arrow-window) 
(: documentation :combination 
"Instantiable flavor for window output from LGP coordinates. 
This flavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
is the flavor to instantiate for window output using the 
current calculation module.")) 



5.1.4 Flavors for LGP Output 

We want to be able to direct output to an LGP or an LGP record file as 
well as to a window. We define another flavor, Igp-pixel-mixin, to be 
mixed in with arrow-parameter-mixin. We can set an instance variable to 
the output stream and make it initable so that we can specify the output 
stream when we make an instance of the flavor we build on 
Igp-pixel-mixin. The output stream will itself be an instance of a flavor. 



(defflavor Igp-pixel-mixin 
(output-stream) 

() 

:initable-1nstance-var1ab1es 

( :required-f lavors arrow-parameter-mixin) 

(: documentation :m1xin 
•Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAMETER-HIXIN is required to calculate the size of the 
figure and position it in the center of the page. The method 
assumes that coordinates are in LGP pixels. This flavor 
should be mixed, along with ARROW-PARANETER-HIXIN, into an 
instantiable flavor for LGP output. When that flavor is 
instantiated, the Instance variable output-stream should be 
initialized.")) 



The methods for this flavor need to do two things: determine the width 
and height of a page and handle :show-lines messages. We get the width 
and height from the values of instance variables for the flavor 
lgp:ba6lc-lgp-stream. This flavor will be a component of the flavor we 
instantiate as the output stream. 
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Finds width and height of a page for LGP output. 
This flavor Is required by ARROW-PARAKETER-NIXIN. Finds the 
values of two Instance variables of LGP:BASIC-LGP-STREAN: 
SI: PAGE-WIDTH and SI: PAGE-HEIGHT. Assumes that 
LGP:BASIC-LGP-STREAH Is Included In output stream to provide 
these instance variables, 
(defmethod (Igp-plxel-mlxin :compute-w1dth-and-he1ght) () 

(setq width (symeval-ln-lnstance output-stream * si: page-width) 

height (symeval-ln-lnstance output-stream *s1:page-he1ght))) 



The :show-lines method is similar to that for windows. Instead of using 
the :draw-liiie message to produce lines, we use two messages to 
lgp:basic-Igp-stream: rsend-command and rsend-coordinates. 



Receives endpoint coordinates and draws lines on LGP stream. 
Arguments are alternating x- and y-coordlnates of endpolnts of 
lines to be drawn. If there are more than two pairs of 
coordinates, assumes that the endpoint of one line Is the 
starting point of the next. Draws a line by sending output 
stream :SEND-COraiAND messages for LGP commands and 
:SEND-COORDINATE messages for LGP coordinates. Assumes that 
flavor LGP:BASIC-LGP-STREAM Is Included In output stream to 
provide these methods, 
(defmethod (Igp-plxel-mlxin :show-11nes) 
(xO yO &rest x-y-pairs) 
;; Send command and coordinates to start drawing lines 
(send self *:send-command-and-coord1 nates #/m xO yO) 
;; "Cddr" down the list created by making all but the first 
;; pair of coordinates an 6rest argument 
(loop for (x y) on x-y-paIrs by #'cddr 

;; Send command and coordinates to draw a line 

do (send self *:send-command-and-coord1nates #/v x y))) 

Sends line-drawing commands to LGP output stream. 

:SEND-CONHAND transmits an LGP command. :SEND-C(X)RDIIfATES 

transmits coordinates of an endpoint of a line to be drawn. 

Assumes that LGP:BASIC-LGP-STREAN Is Included In output stream 

to provide these methods, 
(defmethod (Igp-plxel-mlxin :send-command-and-coord1nates) (cmd x y) 
(send output-stream *:send-command cmd) 
(send output-stream *:send-coord1 nates (fixr x) (fixr y))) 



We can now define an instantiable flavor for the LGP stream that combines 
Igp-pixel-mixin and arrow-parameter-mixin. 
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(defflavor Igp-plxel -stream () 

(1gp-p1x8l-m1x1n arrow-parameter-mlxin) 
(: documentation :cofflb1nat1on 
"Instantlable flavor for arrow output on LGP stream. 
Assumes that the calculation module uses LGP coordinates. 
When this flavor Is Instantiated, the L6P-PIXEL-NIXIN 
Instance variable OUTPUT-STREAM should be Initialized. 
The output stream can be directed to an LGP or a file, 
but It must include flavor LGP:BASIC-LGP-STREAM for 
output to vfork correctly.")) 



5.1 .5 The Top-Level Function 

We are ready to define a top-level function we can call to produce the 
graphic. We start by popping up a choose-variable-values window. We 
allow the user to specify screen, LGP, or file output. We also allow the 
user to choose values for the number of recursion levels and the proportion 
of the page or window to be filled. We let the user decide whether or not 
to stripe the arrows. 



(defvar »dest-str1ng* "Screen" 
"Destination of program output [Screen, LGP, or File]") 

(defvar "output-file* nil 
"Pathname for LGP-record-flle output") 

;;; Top-level function to call to produce arrow graphic. 

;;: Pops up a choose-variable-values window to let user specify 

;;; output destination, number of recursion levels, proportion 

;;; of smaller dimension of page or window to be filled, and 

;;; whether or not to stripe figure. 

(defun do-arrow () 

;; Pop up a choose-variable-values window 
(tv:choose-var1ab1e-va1ues 

'((•do-the-str1pes* "Stripe the arrows?" :boo1ean) 
(*max-depth* "Number of recursion levels" :number) 
(*fm -proportion* 

"Fraction of page or window to be filled" :number) 
(•dest-string* "Output destination" 

:choose ("Screen" "LGP" "File")) 
(•output-file* "Pathname for file output" :PATHNANE)) 
;; Make window wide enough to accommodate long pathnames 
;; and error messages 
*: extra-width 20. 
;; Give user a chance to abort 

♦:marg1n-cho1ces '("Do It" ("Abort" (signal 'sys.-abort))) 
*: label "Choose Options for Graphic")) 



Next we need to take action depending on the output destination the user 
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has chosen. If the variable *flll-proportion* is zero, we just return nil no 
matter what the output destination. If the destination is "Screen", we make 
an instance of arrow-window. We use ttrmiake-window, which creates a 
new window each time we call do-arrow. We could al^ have defined a 
resource of arrow windows (using defwindow-resoiirce), but we might want 
more than one selectable arrow window at a time. 

If we have more than one arrow window, we want each to retain its own 
values for number of recursion levels, proportion of the window to be Hlled, 
and presence or absence of striping. We define three instance variables for 
basic-arrow-window-mixin and make them initable. We initialize them 
when we call tv:make-window from do-arrow. We change the :after 
daemons for basic-arrow-window-mixin to bind the special variables to the 
imtance-variable values. 

(def flavor basic-arrow-window-mixin 
I (do-stripes max-dep fill-prop) 

() 
I :initable-instance-variab1es 

(: required-flavors arrow-parameter-mixin tviwindow) 
(:default-init-plist 
:edges-from *:mouse : minimum-width 200 :minimum-height 200 
:b1inker-p nil :expose-p t) 
(: documentation :mixin ...)) 

(defmethod (basic-arrow-window-mixin :after :init) (ignore) 
I (let ((«f ill-proportion* fill-prop)) 

(send self *:compute-parameters))) 

(defmethod (basic-arrow-window-mixin 

rafter ichange-of-size-or-margins) (&rest Ignore) 
I (let ((«f ill-proportion* fill-prop)) 

(send self *: compute-parameters))) 

(defmethod (basic-arrow-window-mixin tafter :refresh) 
(&optional type) 
;; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 

;; ... or size has changed, 
(eq type *: size-changed)) 
;; If restored from a bit-save array, clear screen first 
(t<hen tv:restored-bits-p 

(send self ':clear-screen)) 
;; Bind global variables to self and instance variables 
(let ((«dest* self) 

I(*do-the-stripes* do-stripes) 
(•max-depth* max-dep)) 
;; Draw the figure 
(draw-arrow-grapbic top-edge right-x top-y)))) 
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(defun do-arrow () 
(tv:choose-var1ab1e-va1ues 



;; If figure Is Infinitely small. Just return nil 
(cond ((= 'fm -proportion* 0) nil) 

;; If screen output, make a window 
((equal 'dest-strlng* "screen") 
(tv:make-w1ndow *arrow-w1ndow 

;; Initialize Instance variables to 
;; values set by the user 
*:do-str1pes *do-the-str1pes« 
*:max-dep •max-depth* 
*:fin-prop 'f Ill-proportion*)))) 



If the output destination is "LGP" or "File", we want to make an instance 
of Igp-pixel-stream with the instance variable stream initialized to an 
appropriate stream. We construct this stream by calling 
si:make-hardcopy-streaiB with an argument that depends on the output 
destination. We use with-open-stream to produce the output on the stream 
and close it when we Hnish. 
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(defun do-arrow () 

(tv:choose-var1ab1e-va1ues 



(cond ((s *fm-proportion* 0) nil) 

;; If screen output, make a window 
((equal 'dest-strlng* "screen") 
(tv: make-window * arrow-window 

;; Initialize Instance variables to 
;; values set by the user 
*:do-str1pes •do-the-str1pes« 
*:max-dep 'max-depth* 
*:fni-prop •fin-proportion*)) 
;; If L6P or file output, use an appropriate stream 
(t (with-open-stream 
(stream 

;; This function returns a stream suitable for 

;; LGP output 

(si :make-hardcopy-stream 

;; Argument Is the output device. For LGP, 
;; use the default hardcopy device. 
(If (equal «dest-str1ng« "Igp") 
si :*default-hardcopy-dev1ce* 
;; For file output, use the correct format 
;; for the hardcopy device and direct 
;: output to the file specified by the user 
( 1 gp : get- 1 gp-record-f 1 1 e-hardcopy-devi ce 
•output-file*)))) 
;; Make an Instance of our LGP output flavor 
(let ((*dest* 

(make- Instance *lgp-p1xel -stream 

;; Initialize Instance 
;; variable to output stream 
*: output-stream stream))) 
;; Position the figure on the page 
(send *dest* *: compute-parameters) 
;; Draw the figure, using Instance-variable values 
;; as arguments 

(draw-arrow-graphic (send 'dest^ 'ttop-edge) 
(send •dest* 'zrlght-x) 
(send •dest^ ':top-y))))))) 



5.1.6 The Arrow Window: Interaction, Processos, and the Mouse 

Suppose we ytBOt to let the user modify the characteristics of the graphic 
for each window. The user might want to change the presence or absence 
of striping, the number of recursion levels, or the proportion of the window 
to be filled. 

One way to install this option is to associate each window with its own 
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process and let the process run in a loop. If the user dicks right on the 
window, we pop up a choose-variable-values window. When the user is 
finished, we refresh the window and wait for the next mouse click. 

We can associate a window with a process by including the flavor 
tv:process-mixin in basic-arrow-window. When we make the window 
(using t?:make-window), we specify a :process init option whose argument 
is the name of the top-level function for the process. When the window is 
created, a new process is created as well. When the window is exposed, the 
process's top-level function is called with one argument, the window. 

(defflavor basic-arrow-window () 

(baslc-arrow-wlndow-mlxln 
arrow-parameter-mlxln 
tv:process-in1x1n 
tv:window) 
(: documentation :comb1nat1on ...)) 

(defun do-arrow () 
(tv:choose-var1ab1e-va1ues 



(cond ((= «fm -proportion* 0) nil) 

;; If screen output, make a window 
((equal *dest-str1ng« "screen") 
(tv: make-window * arrow-window 

;; Initialize Instance variables to 
:; values set by the user 
':do-str1pes 'do-the-strlpes* 
*:max-dep *max-depth« 
*:fm-prop •fin-proportion* 
;; Specify top-level function for the 
;; process associated with the window 
*:process ^window-loop))) 



We next want to be able to handle mouse clicks. We include the flavors 
tv:any-tyi-mixin and tv:list-moase-bnttoiis-inixin in basic-arrow-window. 

When a window is waiting for input and the mouse is cHcked while over the 
window, a blip enters the window's input buffer. A blip is a list whose 
form, with tvzlist-monse-bDttons-iiiixin, is as follows: 

(imouse-batton encoded-click window x y) 

Encoded-click is a fixnum that represents the button clicked. 
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(defflavor basic-arrow-window () 

(baslc-arrow-wlndow-mlxin 
arrow-parameter-mlxln 
tv:any-ty1-in1x1n 
tvzllst-mouse-buttons-mlxln 
tv:process-m1xin 
tv: window) 
(: documentation : combination ...)) 



We also want a mouse documentation string to appear when the mouse is 
over the window: 



(defmethod (baslc-arrow-wlndow-mlxin 

:who-11ne-documentat1on-str1ng) () 

"Provides a mouse documentation line for the window. 
The only option Is to click right and pop up a 
choose-varlable-values window of options for changing 
the graphic on this window." 

"R: Choose-varlable-values options for changing figure on this window") 



We can now write the process function window-loop. This function just 
sends a :main-loop message to the window. We define :main-loop as a 
method for basic-arrow-window-mixin. The method consists of an 
error-restart-loop so that we can return to top level if sys:abort or an 
error is signalled. We send the window an :any-tyi message. If the user 
clicks right, we pop up a choose-variable-values window with the window's 
current value of the variables. When the user exits, we refresh the window 
and wait for another click. If the user aborts, sys:abort is signalled, and we 
restart the loop. 



; Top-level function for process associated with arrow window. 
; The function Is called when the window Is created. Argument Is 
; the window. The function sends the window a :NAIN-LOOP message. 
; This method should be the actual command loop for the process, 
(defun window- loop (window) 
(send window *:ma1n-1oop)) 
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;;; Command loop for window associated with a separate process. 
;;; Consists of an error-restart- loop that handles restarts from errors 
;;; and sys:abort. Walts for iMuse Input. If a right click, pops up a 
;;; choose-var labia- values window to change characteristics of the 
;;; figure. On exit, sets Instance variables to the new values and 
;;; refreshes the window, then waits for another mouse click. Assumes 
;;; blips are lists of the form provided by TV:LIST-MOUSE-BUTTONS-HIXIM. 
(defmethod (baslc-arrow-wlndow-mlxin :ma1n-loop) () 

;; Run forever In a loop. Offer a restart handler If an error 
;; or SYS:ABORT Is signalled. 

(error-restart- loop ((error sys:abort) "Arrow Window Top Level") 
;; Walt for Input 

(let ((char (send self ':any-ty1))) 
;; Pop up window If Input Is a list ... 
(vfhen (and (llstp char) 

;; ... and a mouse click ... 
(eq (first char) *:mouse-button) 
:; ... and a single click on the right button, 
(eq (second char) #\mouse-r-l)) 
;; Bind global variables to Instance-variable values 
(let ((*do-the-str1pes* do-stripes) 
(*max-depth* max-dep) 
(•fill-proportion* fill-prop)) 
; ; Pop up a choose-varlable-values window 
(tv:choose-var1able-values 

'((•do-the-str1pes« "Stripe the arrows?" :boolean) 
(•max-depth* "Nunrtier of recursion levels" :nuiid)er) 
(•fill-proportion* 

"Fraction of window to be filled" :number)) 
; ; Hake the window wide to provide enough room for error 
:; messages. 
': extra -width 20 

; ; Give the user a chance to abort 

* :marg1n-cho1ces *("Do It" ("Abort" (signal *sys:abort))) 
*:label "Choose (^tlons For Graphic") 
;; Set Instance variables to the new values 
(setq do-stripes •do-the-str1pes* 
max-dep •max-depth • 
fill-prop •fin-proportion^) 
;; Recompute size and position of the figure 
(send self *: compute-parameters) 

;; Send : REFRESH message with argument of *:new-vals to make 
;; sure the figure Is redrawn If there Is a bit-save array 
(send self *:refresh *:new-vals)))))) 



We need to change the mf ter :ref resh method for 
basic-arrow-window-Biixin so that it redraws the figure when the values 
are changed even if the window has a bit-save array. 
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(defmethod (baslc-arrow-wlndow-ralxin rafter :refresh) 
(&opt1ona1 type) 
;; Draw figure If not restored froa a bit-save array ... 
(when (or (not tv:restored-b1ts-p) 

;; ... or size has changed ... 
(eq type *:s1ze-changed} 
;; ... or new values for figure parameters, 
(eq type *:new-va1s)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-b1ts-p 

(send self *:c1ear-screen)) 
;; Bind global variables to self and Instance variables 
(let ((«dest* self) 

(*do-the-str1pes* do-stripes) 
(«max-depth* max-dep)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 

Note that we can also manipulate the windows we create by using the 
[Split Screen] and [Edit Screen] options from a system menu. We might 
have more than one arrow window on the screen at the same time. We 
might redisplay the Hgures on these windows at the same time. In this case, 
the scheduler might switch between the arrow window processes, allowing 
each to run for a time until all redisplays are complete. 

Remember that we took care to bind rather than set the global variables in 
the calculation module that hold the state of each arrow. We want the 
values of some variables to be different in each window. Each process 
ftiaintains its own bindings for variables. When the scheduler switches 
processes, bindings in the old process are undone and saved. They are 
restored when the old process resimies. But if we had set the variables, the 
program woiild not have run correctly when the scheduler switched 
processes. The new process might have used variable values set in the old 
process. 



5.1 .7 Signalling Conditions 

We want to add one more refinement to the output module. In our choose- 
variable-values windows, the variable type keywords, such as mamber and 
:pathnaBe, provide for some error checking when users choose new values. 
But two of our numeric variables have further restrictions: *max-depth* 
must be a nonnegative integer, and *flll-proportion* must be a fraction 
between and 1. 

The function tTzchoose-Tariable-Taloes has a rf unction option that lets us 
name a function to be called whenever an item is to be changed. We can 
use this function to check the values of our two variables and signal a 
condition if the values are bad. We then print a m«sage on the window 
and ask the user to proceed by supplying a new value. 
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We start by defining flavors for the conditions we signal. We define a 
general class of error conditions called bad-arrow-Turiable. We then define 
two flavors built on bad-arrow-Toriable: bad-arrow-depth for improper 
values of •max-depth* and bad-arrow-fill-proportion for improper values 
of *f ill-proportion*. For each of these instantiable flavors we define a 
:report method and a :proceed method. The :report method prints a 
string identifying the condition. The :proceed method allows the user to 
proceed from the condition, in this case by supplying a new value. We 
could have more than one :proceed method if we had other ways of 
proceeding. :proceed methods are combined using :case method 
combination. 

If we want to create conditions for bad values of other variables in the 
future, we can simply define new flavors built on bad-arrow-Tariable. 

(defflavor bad-arrow-variable () (error) 
( : documentation 

"Nonlnstantlable class of bad-variable conditions. 
The user might set some variables to impermissible values. 
These conditions are to permit checking for bad values 
beyond the system*s error checking. Instantiable condition 
flavors for specific variables should be built on this 
flavor.")) 



(defflavor bad-arrow-depth () (bad-arrow-varlable) 
( : documentation 
"Proceedable condition: bad value for •MAX-DEPTH*. 
An instantiable condition flavor for lRq>erm1ss1b1e values 
of •MAX-DEPTH*, the number of recursion levels In the 
figure.")) 

;;; Prints string on stream to report bad *MAX-DEPTH* value 
(defmethod (bad-arrow-depth rreport) (stream) 
(format stream "No. of levels was not a " 
nonnegatlve fixnura.")) 



;;: Proceed type method for supplying new value of *MAX-DEPTH* 
(defmethod (bad-arrow-depth :case :proceed :new-depth) 
(&opt1ona1 (dep (prompt-and-read 
*: number 

"Supply new value for " 
no. of recursion levels: "))) 
■Supply a new value for number of recursion levels." 
(values *: new-depth dep)) 
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(defflavor bad-arrow-fm -proportion () (bad-arrow-variable) 
(: documentation 
"Proceedable condition: bad value for *FILL-PROPORTION*. 
An Instantlable condition flavor for Impermissible values of 
*FILL-PROPORTION*, the fraction of the smaller dimension of 
the page or window that the figure Is to fill.")) 

;;; Prints string on stream to report bad •FILL- PROPORTION* value 
(defmethod (bad-arrow-f Ill-proportion :report) (stream) 
(format stream "Proportion was not a fraction between " 
and 1.")) 

; ; ; Proceed type method for new value of *F ILL- PROPORTION* 
(defmethod (bad-arrow-f Ill-proportion :case : proceed 

: new-proportion ) 
(&opt1onal (prop (prompt-and-read 
* : number 

"Supply new fraction of bounds " 
be filled: "))) 
"Supply a new fraction of page or window to be filled." 
(values *: new-proportion prop)) 



Next we write the function, check-item, to be called when a variable value 
is changed. The function is called with four arguments: the choose- 
variable-values window, the variable, and the variable's old and new values. 
We use condition-bind to bind a handler for our two conditions. This 
handler will be called if we signal the conditions from within the 
condition-bind. If we do find a bad variable value, we we expect the call 
to signal to return the two values from the :proceed method: the proceed 
type and the new variable value. We then check the new value and, if it is 
good, set the variable to the new value. Finally, we refresh the window and 
return t. 
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Called when a value changes In choose-var labia- values window. 
Arguments are the window, the variable, and Its old and new values, 
Binds handlers for conditions for Impernlsslble values. If new 
value Is OK, sets variable to the new value, refreshes window, and 
returns t. If value Is not OK, signals the appropriate condition. 
When SIGNAL returns, presumably with a new variable value, checks 
the new value In the same way It checks a new value that comes 
from the window, 
(defun check-Item (cw-wlndow var old-val new-val) 

We don't use the old value. To avoid a compiler complaint. 
Just evaluate It and Ignore It. We could also use IGIK>RE 
Instead of OLD-VAL In the argllst, but then the argllst 
%«ou1d be less meaningful, 
old-val 

;; Bind handlers for the conditions we might signal 
(condition-bind ((bad-arrow-depth *bad-arrow-var-hand1er) 
(bad-arrow-flll-proportlon 
*bad-arrow-var-hand1er ) ) 
(when (eq var **max-depth«) 

;; •MAX-DEPTH* must be nonnegatlve fixnum 
(loop until (and (fixp new-val) (2 new-val 0)) 

;: If It's not, bind QUERY- 10 to the window and 
:; signal a condition. SIGNAL should return 
:; two values, the proceed type and the new 
:; value from the proceed method. Ignore the 
;; proceed type and set NEW-VAL to the new 
;; value, 
do (let ((query-1o cw-wlndow)) 

(multiple-value (nil new-val) 
(signal *bad-arrow-depth))))) 
(*<hen (eq var '•fill -proportion*) 

; ; •FILL-PROPORTION* must be between and 1 
(loop until (and (^ new-val 0) (^ new-val 1)) 

;; If It's not, bind QUERY-IO to the window and 
;; signal a condition. SIGNAL should return 
;; two values, the proceed type and the new 
;; value from the proceed method. Ignore the 
:; proceed type and set NEW-VAL to the new 
;; value. 

do (let (( query- 1o cw-wlndow)) 
(multiple-value (nil new-val) 
(signal 'bad-arrow-f 1 1 l-proport1on) ) ) ) ) 
;; Variable value Is now OK. Set variable to the new value. 
;; Note that we DO want to evaluate VAR. 
(set var new-val) 
;; Refresh the window 
(send cw-wlndow *: refresh) 
;; Return t 
t)) 



Next we need to add the zfanction option to our calls to 
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tT:choose-Tariable-Talne$ in the function do-arrows and the :main-loop 
method of basic-arrow-window-mlxin: 

(defun do-arrow () 

;; Pop up a choose-varlable-values window 
(tv:choose-var1ab1e-va1uas 

♦((«do-the-str1pes* "Stripe th« arrows?' :boo1ean) 
(*max-depth* "Mumber of recursion levels" tnumber) 
( 'fl 1 1 -proportion* 

"Fraction of page or window to be filled" :number) 
(•dest-string* "Output destination" 

:choose ("Screen" "LGP" "File")) 
(•output-file* "Pathname for file (Hitput" :pathnaiBe)) 
;; Hake window wide enough to acconmodate long pathnames 
;; and error messages 
': extra-width 20. 

;; Call this function when a value Is changed 
•:funct1on *check-1tem 
;; Give user a chance to abort 

':marg1n-cho1ces '("Do It" ("Abort" (signal 'sysiabort))) 
*: label "Choose Options for Graphic") 
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(defnethod (baslc-arrow-wlndow-mixln :ina1n-1oop) () 

;; Run forever In a loop. Offer a restart handler If an error 
;; or sys:abort Is signalled. 

(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
;; Walt for Input 

(let ((char (send self *:any-ty1))) 
;; Pop up window If Input Is a list ... 
(when (and (llstp char) 

;; ... and a mouse click ... 
(eq (first char) *:nouse-button) 
;; ... and a single click on the right button, 
(eq (second char) #\mouse-r-l)) 
;; Bind global variables to Instance-variable values 
(let ((«do-the-str1pes* do-stripes) 
(*niax-depth* nax-dep) 
(•fill-proportion* fill-prop)) 
;; Pop up a choose-varlable-values window 
(tv:choose-var1ab1e-values 

*((*do-the-str1pes« "Stripe the arrows?" :boolean) 
(•fflax-depth* "Number of recursion levels" :number) 
(•fill-proportion* 

■Fraction of window to be filled" :nuiid>er)) 
;; Hake the window wide to provide enough room for error 
;; messages. 
':extra-w1dth 20 

;: Call a function to check for errors when values change 
'rfunctlon *check-1tem 
;; Give the user a chance to abort 

* :marg1n-cho1ces '("Do It" ("Abort" (signal *sys:abort))) 
*:label "Choose Options for Graphic") 
; ; Set Instance variables to the new values 
(setq do-stripes •do-the-str1pes^ 
max-dep •max-depth^ 
fill-prop •fill-proportion^) 
;; Recompute size and position of the figure 
(send self *: compute-parameters) 

;; Send :REFRESH message with argument of *:new-vals to make 
;; sure the figure Is redrawn If there Is a bit-save array 
(send self * .-refresh *:new-vals)))))) 

Finally, we need to write a handler for the two conditions. When a 
condition is signalled, the handler is called with one argument, the object of 
the flavor of condition that is signalled. In check-item, we call signal with 
qaery-io bound to the choose-variable-values window. The handler checks 
to be sure there is a proceed type for the object. If so, the handler turns 
on a blinker on the window and sends the :report and :proceed messages to 
the condition object Finally, it turns off the blinker and passes back to its 
caller the two values that the :proceed method returns. 
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Actually, the handler we define doesn't depend on the binding of qaery-lo 
to the window. If qoery-io is not bound to a window — that is, to an 
instance of a flavor built on tvrsheet — the handler won't try to turn on a 
blinker. If qnery-io is bound to a window, the handler first looks (using 
tT:sheet-f ollowing-blinker) for an existing blinker that follows the cursor. 
If it doesn't find one, it makes a new blinker (using tTzmake-blinker). It 
enclose the handling operation in an anwind-protect to be sure that the 
blinker is turned off in case of a nonlocal exit. 



; Handler for bad value of •HAX-DEPTH* or *FILL-PROPORTION«. 
; Argument Is the condition object created by SIGNAL. Uses QUERY-IO 
; stream to report condition. Sends the condition object a : PROCEED 
; message and passes back the values it returns, 
(defun bad-arrow-var-handler (cond-obj &aux b1) 

;; Find out whether this object has the right proceed type. 

;; If not, return nil. 

(if (send cond-obj *: proceed- type-p 

(cond ((typep cond-obJ * bad-arrow-depth) *:new-depth) 
((typep cond-obJ 'bad-arrcw-fin-proportlon) 
* :new-proport1on) ) ) 
;; Enclose the handling operation In an UNVflND-PROTECT so that 
;; If we use a blinker we are sure to turn It off 
(unwind-protect 
(progn 

;; Use a blinker If the QUERY-IO stream Is a window 
(setq bl (If (typep query- 1o *tv: sheet) 

;; If a cursor-following blinker exists, use It 
(or (tvtsheet-followlng-bllnker query-lo) 
;; Otherwise, make a new blinker 
(tv:make-b1 Inker query-lo 

*tv:rectangu1ar-b1 Inker 
':fonow-p t)))) 
;; If a blinker, make It bTInk 
(If bl (send bl 'rset-vlslblllty 'rblink)) 
;; Alert the user 
(tv:beep) 

;; Send a report, presumably describing the condition 
(send cond-obJ *: report query-lo) 

;; Send object a : PROCEED message and return the values 
; ; that the method returns 
(send cond-obJ *: proceed 

(cond ((typep cond-obJ * bad-arrow-depth) *:new-depth) 
((typep cond-obJ 'bad-arrow-f1 11 -proportion) 
' : new-pr opor t Ion)))) 
;; If a blinker, turn It off 
(If bl (send bl 'rset-vlslblllty nil))))) 



After we have deHned all the flavors and methods for the output module, 
we insert a compile-flavor-methods form in the Hie. Without this macro, 
combined methods are compiled and flavor data structures generated when 
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we make the first instance of a flavor — that is, at run time. 
conpile-flaYor-methods speeds nm-time operation by causing combined 
methods to be compiled at compile time and data structures to be generated 
at load time. It is useful only for flavors that will be instantiated, not for 
flavors that are only components of instantiated flavors. 

(complle-flavor-methods arrow-window Igp-plxel -stream 

bad-arrow-depth bad-arrow-fill-proportion) 



5.2 Programming Aids for Fiavors and Windows 

Some editor commands and Lisp functions provide information about flavors. You can find out 
about component flavors, methods, instance variables, init keywords, and documentation. Using 
the Inspector, you can examine instance variables and methods for instances of flavors (see 
section 4.7, page 94). If a flavor has gettable instance variables, you can obtain their values by 
sending messages to instances of the flavor. 

These commands and functions are useful for finding information about windows as well. 
Because windows are instances of flavors, you can retrieve characteristics that are stored in 
gettable instance variables by sending messages to the windows (see Introduction to Using the 
Window System). If a window is exposed, you can examine and alter some characteristics by 
clicking on the [Attributes] item in the system menu. Clicking on [Attributes] pops up a 
choose-variable-values window for such characteristics as font, label, margins, and vertical 
spacing between lines. 

As with other deflnitions. Edit Definition (m-. ) prepares to edit deflnitions of flavors and 
methods. Section 5.2.2 (page 129) describes how to use this command to edit method 
definitions. 



5.2.1 General Information 

The facilities that display general information about a flavor are Describe 
Flavor (»-X) and describe-flavor. These display somewhat different 
descriptions of a flavor. 

A useful predicate for instances of flavors is typep. Given an instance and 
a flavor name, typep returns t if the instance includes the flavor as a 
component. 

Example 

In handling bad values for the variables *Bax-depth* and 
*fiIl-proportioii*, we want to be sure that qnery-io is bound to a window 
before turning on a blinker. We find out whether the object bound to 
qoery-lo is built on tTzsheet by using typep: 

(typep query- 1o *tv: sheet) 
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Reference 

Describe Flavor (»-X) 



(describe-flavor flavor-nami^ 



(typep org type) 



Displays a d^cription of a flavor that 
includes the names of instance 
variables and component flavors and 
any documentation added by the 
:do€amentation option to defflavor. 
Also displays init keywords and 
inherited methods and instance 
variables. Names of flavors and 
methods in the display are mouse 
sensitive. 

Prints a description of a flavor that 
includes the names of instance 
variables and component flavors and 
any documentation added by the 
tdocamentation option to defflaTor. 

When org is an instance of a flavor 
and type is a flavor name, returns t if 
the instance includes the flavor as a 
component or nil if it does not If 
type is omitted, returns a symbol 
representing the flavor of the 
instance. 



5.2.2 Methods 



Four Zmacs commands display information about the methods that handle 
messages to instances of flavors. For instances of flavors built on 
shvanilla-flavor — that is, for nearly all flavors — you can send messages 
to find out which messages the object handles and whether or not it handles 
a specific message. 

You can use the Zmacs command Edit Definition (m-. ) to edit the 
deHnition of a method. Specify a method by typing a representation of its 
fimction spec. This is a list of the following form: 

(:nethod flavor type message 



When typing this representation for Edit Definition (m-. ), type is optional. 
If the method has a type, Zmacs will try to find the definition and ask you 
whether or not that deHnition is the one you want. 

You might know the name of a method but not the name of its flavor. Use 
List Methods (m~X) to find methods for all flavors that handle a message. 
You can click on one of the method names displayed to edit its definition. 
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Example 

We want to edit the definition of the :main-loop method for 

basic-arrow-window-mixin. We use Edit Definition (n-. ) and type: 

(:method baslc-arrow-wlndow-nlxin :na1n-1oop) 



Example 

We want to find out which methods handle rshow-lines messages and how 

the methods handle the messages. List Methods (n-X) displays the following 

methods: 

Methods for :SHOW-LINES 

(:METHOD BASIC-ARROW-WINDOW-NIXIN :SHOW-LINES) 

(:NETHOD L6P-PIXEL-KIXIN :SHOW-LINES) 

We can click on one of the method names or press c. to edit the 
definition. We also could have found the source code directly by using Edit 
Methods (m-X). 

Example 

We want to Hnd out which methods are called when the system sends an 
dnit message to arrow-window. List Combined Methods (n-X) prompts for 
message and flavor names and displays the following methods, in the order 
in which they are called: 

C(Mirii)1ned method for :INIT message to ARROW-WINDOW flavor 

(:NETHOO TV:SHEET :WRAPPER :INIT) 

(rMETHOD TV:STREAM-MIXIM rBEFORE rlHIT) 

(:NETHOD TV:BORDERS-MIXIN rBEFORE :INIT) 

(:METHOO TV:ESSENTIAL-LABEL-MIXIN :BEFORE rIMIT) 

(:HETHOD TV: ESSENTIAL-WINDOW rBEFORE rINIT) 

(rHETHOD TV r SHEET rINIT) 

(rHETHOD TV: ESSENTIAL-SET-EDGES rAFTER rINIT) 

(rMETHOD TVrLABEL-MIXIN rAFTER :INIT) 

(:METHOD TVrPROCESS-MIXIN rAFTER :INIT) 

(rMETHOD BASIC-ARROW-WINDOW-MIXIN rAFTER :INIT) 



Reference 

List Methods (m-X) Lists methods for all flavors that 

handle a specifled message. Press c-. 

to edit the definitions of the methods 

listed. 

Edit Methods (m-X) Prepares to edit definitions of 
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List Combined Methods (n-X) 



Edit Combined Methods (m-X) 



methods for all flavors that handle a 
specified message. Press c-. to edit 
subsequent definitions. 

Lists all the methods that would be 
called if a specified message were sent 
to an instance of a speciHed flavor. 
Press C-. to edit the deHnitions of 
the methods listed. 

Prepares to edit deHnitions of 
methods that would be called if a 
specified message were sent to an 
instance of a specified flavor. Press 
C-. to edit subsequent definitions. 

(send instance ':which-operations) Returns a list of messages that 

instance can handle. 

(send instance ':operation-handled-p message) 

Returns t if instance has a handler for 
message or nil if it does not. 

Returns the method that handles 
message to objectf or nil if obja:t has 
no handler for messc^e 



(get-handler-for object message 



5.2.3 Init Keywords 

si:flayor-allowed-init-keywords retrieve the init keywords allowed for a 
flavor. 

Example 

We want to find the allowed init keywords for Igp-pixel-stream. 

si:flavor-allowed-init-keywords returns the following list: 

(:DO-STRIPES :FILL-PROP :MAX-DEP : OUTPUT-STREAM) 

These are all keywords for initable instance variables, the first three from 
arrow-parameter-mixin and the last from Igp-pixel-mixin. 



Reference 
(si:fla?or-allowed-init-keywords/7izwr-name) 

Returns a Ust of any init keywords a 
flavor can take. 
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Appendix A 
Calculation Module for the Sample Program 



The program used as an example in this document draws the recursive arrow graphic on the 
document's cover. This appendix contains Lisp code that calculates coordinates for the 
endpoints of the lines that compose the figure. The code produces output by sending messages 
to instances of flavors defined in another file. Appendix B (page 147) contains the code for 
the flavors and methods that mediate between the program and the system output operations. 
Appendix C (page 165) contains a reproduction of the LGP graphic the program produces. 

;;; -«- Hode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -*- 
:;; Copyright (c) 1983 Symbolics, Inc. 



#1 

This file contains the calculation module for a program that 
reproduces the recursive arrow graphic printed on the covers 
of most Symbolics documents. The module calculates the 
coordinates of the endpoints of line segments to be drawn. 
It transmits these coordinates to a separate output module* 
which contains the code needed to produce the figure on an 
appropriate output device. 

We use paper coordinates, origin at bottom left. 

Each arrow In the figure can be seen as Inscribed In a square 
whose apex Is at (apex-x, apex-y). Each arrow has a head and 
a shaft. Top-edge Is the top edge of each arrow, one of the 
sides of the arrowhead. There are two classes of arrow In 
the figure: The small arrows are the general case, and the 
large, outer arrow Is unique. The differences are the 
structures of the shafts and the recursive appearance of 
the small arrows. 

The module uses special variables to store Information about 
the current arrow. Including the length of the top edge and 
the coordinates of the vertexes. 

The module first calculates coordinates for the vertexes of 
the large, outer arrow. If the arrows are to be striped. It 
determines the endpoints of the lines that make up the large 
arrow*s stripes, first In the head and then In the shaft. 
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The module then recursively calculates coordinates for each of 
the small arrows Inside the figure. It outlines and stripes 
one arrow at a time. For each arrow, the module first 
calculates the coordinates of the vertexes of the head. If the 
arrows are to be striped. It then determines the coordinates of 
the endpolnts of the lines that make up the current arrow* s 
stripes, first In the head and then In the shaft. 

The output module Initiates the calculation module by calling 
DRAW-ARROW-GRAPHIC with three arguments: the length of the 
f1gure*s top edge and the coordinates of the top right point 
(pO In the large arrow). This module transmits coordinates to 
the output module by sending :SHOW-LINES messages to Instances 
of output flavors. The arguments to :SHOW-LINES are the 
coordinates of the endpolnts of lines to be drawn. The current 
Instance of the output flavor Is the value of the special variable 
•DEST*. 

(apex-x, apex-y) 
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Points 3 and 4 are obscured, except In the case of the big arrow. 



;;; Following are declarations for special variables and constants 

(defconst *dl« 0.15 
"Proportion of distance filled in between upper right stripes") 

(defconst 'dZ* 0.75 
"Proportion of distance filled in between lower left stripes") 

(defconst *str1pe-d1stance* 20 
"Horizontal distance In pixels between stripes of large arrow") 

(defconst •max-depth* 7 
"Number of levels of recursion") 

(defconst *do-the-str1pes* t 
"If T, permits striping") 

(defconst 'dest* nil 
"(ttiject to which output Is sent") 

(defvar *depth* 
"Current level of recursion") 

(defvar *top-edge« nil 
"Length of the top edge of the arrow") 

(defvar *top-edge-2* nil 
"Half the length of the top edge of the arrow") 

(defvar •top-edge-4* nil 
"One-fourth the length of the top edge of the arrow") 

(defvar •x2* nil 
"X-coord of projection of lower left stripe on top edge") 

(defvar *str1pe-d* nil 
"Horizontal distance In pixels between stripes") 

(defvar *p0x* nil 
"X-coordlnate of the tip of the arrow") 

(defvar *p0y* nil 
"Y-coordlnate of the tip of the arrow") 

(defvar 'plx* nil 
"X-coordlnate of point pi In the arrow") 
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(defvar 'ply* nil 
"Y-coordlnate of point pi In the arrow" 

(defvar 'pZx* nil 
"X-coordlnate of point p2 In the arrow* 

(defvar •pZy* nil 
"Y-coordlnate of point p2 In the arrow" 

(defvar "pSx* nil 
"X-coordlnate of point p3 In the arrow" 

(defvar "pSy* nil 
"Y-coordlnate of point p3 In the arrow" 

(defvar «p4x* nil 
"X-coordlnate of point p4 In the arrow" 

(defvar *pAy* nil 
"Y-coordlnate of point p4 In the arrow" 

(defvar "pSx* nil 
"X-coordlnate of point p5 In the arrow" 

(defvar 'pSy* nil 
"Y-coordlnate of point p5 In the arrow" 

(defvar "pex* nil 

"X-coordlnate of point p6 In the arrow" 

(defvar 'pey* nil 
"Y-coordlnate of point p6 In the arrow" 



;;; Following are the controlling functions for this module 
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Function controlling the calculation module. 

Controls the calculation of the coordinates of the endpolnts of the 
lines that make up the figure. The three arguments are the length of 
the top edge and the coordinates of the top right point of the large 
arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow 
and then calls DO-ARROWS to draw the smaller ones, 
(defun draw-arrow-graphic (•top-edge* «pOx« *pOy«) 
;; Bind global variables 
(let ((«top-edge-2« (// 'top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4)) 

;; Compute horizontal distance between stripes In the large 
;; arrow, assuming 64 stripes In the large arrowhead. 
(*str1pe-d1stance* (// *top-edge* 64))) 
(draw-big-arrow) ;Draw large arrow 

;; Length of the top-edge for the first small arrow Is half the 
;; length for the large arrow. Bind new coordinates for the top 
;; right point of the small arrow, 
(let ((*top-edge* *top-edge-2*) 

(*pOx« (- *pOx* *top-edge-2*)) 
(«pOy* (- *pOy* *top-edge-2*)) 
(•depth* 0)) 
(do-arrows)))) ;Draw small arrows 

Recursive function controlling drawing of the small arrows. 
If below the maxlimjm recursion level, draws a small arrow. Binds 
new values for depth, top edge, and coordinates of top right point, 
and calls self recursively to draw a left-hand child arrow. Binds 
special variables again and calls self to draw a right-hand child 
arrow, 
(defun do-arrows () 

;; Don*t exceed maximum recursion level 
(when (< *depth* *max-depth*) 

;; Bind values for half and one-fourth of top edge 
(let ((•top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 

;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow, 
(let ((*depth* (1* *depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (♦ *top-edge-4* (- *pOx* *top-edge*))) 
(*pOy* (- *pOy* *top-edge-4*))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow, 
(let ((*depth* {1* *depth*)) 

(«top-edge* *top-edge-2*) 
(*pOx* (- *pOx* *top-edge-4*)') 
(*pOy* (♦ *top-edge-4* (- *pOy* *top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 
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The following functions are comnon to the large and small arrows 



Calculates coordinates of points visible In large and small arrows. 
The four points that bound the head of each arrow are the only ones 
visible In the small arrows. Points 3 and 4 — the base of the arrow 
— are obscured, except In the large arrow. We calculate these In 
compute-arrow-shaft-polnts. 



(defun compute-arrowhead-points (} 
(let* ((plx (- 'pOx* nop-edge*)) 
(ply 'pOy*) 

(p2x (♦ plx *top-edge-4*)) 
(p2y (- 'pOy* •top-edge-4*)) 
(p6x *pOx*) 

(p6y (- 'pOy* *top-edge*)) 
(p5x (- "pOx* •top-edge-4*)) 
(p5y (♦ p6y *top-edge-4*))) 
(values plx ply p2x p2y p5x p5y p6x p6y))) 



X-coord, 
Y-coord, 
X-coord, 
Y-coord, 
X-coord, 
Y-coord, 
X-coord, 
Y-coord, 



point 1 
point 1 
point 2 
point 2 
point 6 
point 6 
point 5 
point 5 



: Calculates horizontal distance between stripes. 
; Distance Is a fraction of the distance between stripes for the 
; large arrow. The divisor depends on the level of recursion. 
; Distance divides length of top edge evenly when possible to 
; maintain continuity between head and shaft of arrow, 
(defun compute-strlpe-d () 

;; Distance should be at least 3 pixels so that there Is some 
;; white space between lines. 
(If a 'stripe-distance* 3) 3 

;; First find a fraction of «STRIPE-DISTANCE* that depends 
;; on recursion level 

(loop for dist a (fixr (// *str1pe-d1stance* 

(selectq *depth* 
(0 2) 
(1 4) 
(2 2) 
(3 1.5) 
(4 1.5) 

(otherwise 2)))) 
;; Increment If It doesnH divide *TOP-EDGE* evenly 
then (1-t- dist) 

when (a (\ *top-edge* dist)) 
;; Stop when no remainder. Oon*t return a value 
;; less than 3. 
do (return (If (^ dist 3) 3 dist))))) 
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Calculates the nun^er of lines that compose each stripe. 
Calls COMPUTE-DENS to calculate the proportion of distance 
between stripes to be filled, then iiRiltlplles by the actual 
distance between stripes. Makes sure that there Is at least 
one line and that there aren*t too nany lines to leave some 
white space, 
(defun coiq>ute-n lines (x) 

;; Can COMPUTE-DENS and multiply result by 'STRIPE-D* 
(let ((nl (fix (• 'strlpe-d* (compute-dens x))))) 
;; Supply at least one line 
(cond {(^ nl 1) 1} 

;; But leave some white space between lines 
((i nl (- *str1pe-d* 1)) (- «str1pe-d* 2)) 
(t nl)))) 

Calculates proportion of distance filled In between each stripe. 
The argument Is the x-coordlnate of the projection of the current 
stripe onto the line formed by the top edge. Determines where the 
projection of the current stripe Is on this line In relation to the 
distance from first to last stripes In the arrow. Multiplies this 
fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe, 
(defun compute-dens (x) 
(♦ 'dl* (• (- *d2* 'dl*) 

(// (- X «pOx«) (float {' *x2* "pOx*)))))) 



The following two functions stripe the arrowheads. The 
heads of the large and small arrows are Identical, so tra 
use the same functions to stripe both. 

Function controlling striping of the head of each arrow. 
Determines coordinates of starting and ending points for each 
stripe. Calls COMPUTE -NLINES to determine number of lines for 
the stripe. Calls DRAW-ARROWHEAD- LINES to draw the lines that 
make up each stripe, 
(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- «pOx« «top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from 'pOx* by 'strlpe-d* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance bet«reen stripes. 

for end-y downfrom «pOy« by «str1pe-d* 

;; Find number of lines In the stripe 

for n lines - (compute-n lines start-x) 

;; Draw the lines that make up the stripe 

do (draw-arrowhead- lines n lines start-x end-y last-x))) 
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;;; Draws the lines that make up each stripe In an arrowhead. 
;;: Arguments are number of lines In the stripe, starting x-coord 
;;; and ending y-coord of first line, and x-coord of top of last 
;;; stripe to be drawn. Decrements by one pixel when drawing each 
;;; line. 

(defun draw-arrowhead- lines (nllnes start-x end-y last-x) 
; ; Set up a counter 
(loop for 1 from below nllnes 

;; Find starting x-coord» subtracting counter from first 

;; x-coord 

for first-x s (- start-x 1) 

;; Hake sure we don*t go past the end of the arrowhead 

while (< last-x fIrst-x) 

;; Draw a line 

do (send 'dest* *: show- lines 

fIrst-x 'pOy* 'pOx* (- end-y 1)))) 



;;; The following functions draw and stripe the large arrow 

;;; Function controlling drawing of the large arrow. 

;;; Calls functions to find coordinates of vertexes of the arrow. 

;;; Outlines the arrow. Binds distance between stripes and x-coord 

;;; of projection of last stripe onto top edge. Finally, stripes 

;;; head and shaft of arrow when required. 

(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multlple-value-blnd 
(«plx* 'ply* 'pax* "pZy* 'pSx* *p5y« 'pex* 'pCy*) 

(compute-arrowhead-polnts) 
;; Determine coordinates of shaft vertexes 
(multlple-value-blnd 
(«p3x« 'pay* •p4x« •p4y«) 

(conpute-arrow-shaft-polnts) 
(draw-blg-outllne) ;0utl1ne arrow 

(when 'do-the-strlpes* 

;; Bind distance between stripes and x-coord of projection 
;; of last stripe onto top edge 
(let ((^strlpe-d* •stripe-distance*) 

(•x2« (- 'pOx* «top-edge« •top-edge*))) 
(stripe-arrowhead) ;Str1pe head 

(str1pe-b1g-arrow-shaft)))))) ;Str1pe shaft 

;;; Calculates coordinates for vertexes of shaft of large arrow. 
;;; These points are obscured and not drawn for the small arrows, 
(defun compute-arrow-shaft-points () 



(values (- *plx* •top-edge-4*) 

(- *p2y* 'top-edge-Z*) 
*p2x* 

(- 'pZy* 'top-edge*))) 



X-coord of point 3 
Y-coord of point 3 
X-coord of point 4 
Y-coord of point 4 
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;;; Draws the outline of the large arrow. 

(defun draw-big-outline () 
(send «dest* *:show-1ines 

•pOx« •pOy* 'plx* 'ply* 'pZx* *p2y« •pZx* 'pSy* 
•p4x* •p4y« 'pSx* «p5y« 'pex* 'pGy* 'pOx* *pOy*)) 



; The next seven functions stripe the shaft of the large arrow. 
; First is a controlling function, then three functions to stripe 
; the left side and three more to stripe the right. 

: Function controlling striping of the shaft of the large arrow. 
; Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
; and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side, 
(defun stripe-big-arrow-shaft () 
( str i pe-b 1 g-arrow-shaf t- 1 eft ) 
(stripe-b1g-arrow-shaft-r1ght)) 

Function controlling striping of left side of big arrow's shaft. 
Iterates over the triangles that make up the shaft. Determines 
coordinates of the apex and bottom right point of each triangle. 
Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle, 
(defun stripe-big-arrow-shaft- left () 

;; Set up a counter for depth. Don't exceed maximum recursion 

; ; level . 

(loop for shaft-depth from below *fflax-depth* 

;; Find current top edge and Its fractions 

for top-edge « 'top-edge* then (// top-edge 2) 

for top-edge-2 = (// top-edge 2) 

for top-edge-4 « (// top-edge 4) 

;; Find coordinates of apex of triangle 

for apex-x ■ •p2x* then (- apex-x top-edge-2) 

for apex-y * •p2y« then (- apex-y top-edge-2) 

;; Find x-coord of bottom right vertex 

for right-x « (♦ apex-x top-edge-4) 

;; Find y-coord of bottom edge of triangle 

for bottom-y * (- apex-y top-edge-4) 

;; Find the x-coord of the projection of the first 

;; stripe onto top edge 

for xoff s (- 'pOx* nop-edge*) then (- xoff top-edge) 

;; Stripe each triangle 

do (draw-big-arrow-shaft-stripes-left 

top-edge-4 apex-x apex-y right-x bottom-y xoff))) 
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;;; Stripes each triangle In left side of big arrow's shaft. 
;;; Arguments are one-fourth current top edge, x- and y-coords 
;;; of apex of triangle, x- and y-coords of bottom right vertex, 
;;; and x-coord of projection of first stripe onto top edge. 
;;; Determines coordinates of starting and ending points for 
;;; each stripe. Finds number of lines in the stripe. Calls 
;;; DRAW-BIG-ARROW-SHAFT-LINES-LEFT to draw the lines that 
;;; make up each stripe, 
(defun draw-blg-arrow-shaft-strl pes- left 

(top-edge-4 apex-x apex-y right-x bottom-y xoff ) 
(loop with half-distance * (// *str1pe-d1stance* 2) 

;; Find x-coord of last stripe In triangle 

with last-x s (- apex-x top-edge-4) 

;; Find x-coord of top of each stripe, decrementing 

;; from the apex by HALF the horizontal distance 

;; between stripes. Stop at last stripe. 

for start-x from apex-x by half-distance above last-x 

;; Find y-coord of top of stripe 

for start-y downfrom apex-y by ha If-dl stance 

; ; Find x-coord of endpoint of stripe 

for end-x downfrom rIght-x by *str1pe-d1stance* 

;; Find number of lines In the stripe 

for nllnes » (compute-n lines (- xoff (- rIght-x end-x))) 

;; Draw a stripe 

do (draw-big-arrow-shaft- lines- left 

nllnes start-x start-y end-x bottom-y last-x))) 

;;; Draws the lines for a stripe on left side of big arrow's shaft. 
;;; Arguments are nuii4)er of lines In the stripe, coords of starting 
;;; and ending points for first line, and x-coord of last stripe to 
;;; be drawn, 
(defun draw-blg-arrow-shaft-llnes-left 

(nllnes start-x start-y end-x end-y last-x) 
;; Set up two counters -- we need to draw two lines at once 
(loop for 1 frcHB 

for 12 from by 2 

;; Find x-coord of top of first line In stripe 

for first-x = (- start-x 1) 

;: Don't exceed number of lines In stripe 

while « 12 nllnes) 

;; Don't go past the end of the triangle 

while « last-x fIrst-x) 

;; Draw a line 

do (send *dest* ': show- lines fIrst-x (- start-y 1) 

(- end-x 12) end-y) 
;; Draw a second line. The two lines are a refinement 
;; to stagger the endpolnts of the lines so the diagonal 
;; edge looks neat. 

(send 'dest* ':show-11nes fIrst-x (- start-y 1 1) 
(- end-x 12 1) end-y))) 



Progrcan Development Tools and Techniques 143 

Symbolics, Inc. 



;; Function controlling striping of right side of big arrow*s shaft. 
;; Iterates over the triangles that nake up the shaft. Detemlnes 
;; coordinates of the top point of each triangle. Calls 
:; ORAW-BIG-ARROW-SHAFT-STRIPES-RIGHT to stripe each triangle, 
(defun strlpe-blg-arrow-shaft-rlght () 
;; Set up a counter for depth. Don*t exceed naxlmum recursion 
;; level. 

(loop for shaft-depth from below •nax-depth* 
;; Find new top edge and Its fractions 
for top-edge « ^top-edge* then (// top-edge 2) 
for top-edge-2 » (// top-edge 2) 
for top-edge-4 - {N top-edge 4} 
;; Find coords of top point of triangle 
for start-x « (♦ *p2x* top-edge-4) 
for top-y « (- *p2y« *top-edge-4«) 
then (- top-y top-edge-2 top-edge-4) 
;; Find x-coord of projection of first stripe onto 
; ; top-edge 

for xoff = (- 'pOx* *top-edge*) then (- xoff top-edge) 
;; Stripe the triangle 
do (draw-blg-arrow-shaft-strlpes-rlght 

top-edge-2 top-edge-4 start-x top-y xoff))) 

;; Stripes each triangle In right side of big arrow's shaft. 
;; Arguments are one-half and one-fourth of current top edge, 
;; coords of top point of the triangle, and x-coord of projection 
;; of first stripe onto top edge. Determines coordinates of 
;; starting and ending points for each stripe. Finds number of 
;; lines that make up the stripe. Calls 
;; DRAW-BIG-ARROW-SHAFT-LINES-RIGHT to draw a stripe, 
(defun draw-blg-arrow-shaft-strlpes-rlght 

(top-edge-2 top-edge-4 start-x top-y xoff) 
(loop with half-distance « (// *str1pe-d1 stance* 2) 
;; Find y-coord of last stripe In triangle 
with last-y * (- top-y top-edge-2) 
;; Find y-coord of starting point of stripe. Oon*t go 
;; past the end of the triangle. 

for start-y from top-y by *str1pe-d1 stance* above last-y 
;; Find coords of ending point of the stripe, decrementing 
;; by HALF the horizontal distance between stripes 
for end-x downfrom (* start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half -distance 
;; Find number of lines that make up the stripe 
for nllnes = (compute-n lines (- xoff (- top-y start-y))) 
:; Draw a stripe 
do ( draw-b 1 g-arrow- shaft- 1 1 nes-r 1 gh t 

nllnes start-x start-y end-x end-y last-y))) 
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Draws the lines for a stripe on right side of big arrow's shaft. 
Arguments are number of lines In the stripe, coordinates of starting 
and ending points for the first line, and y-coord of last stripe In 
the triangle. 
( def un draw-bl g-arrow-shaf t- 1 1 nes-r 1 gh t 

(nllnes start-x start-y end-x end-y last-y) 
;; Set up two counters — we need to draw two lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find y-coord of ending point of line 
for stop-y = (- end-y 1) 

;; Don*t exceed nui^er of lines In the stripe 
while « 12 nllnes) 

;; Don*t go past the bottom of the triangle 
while (< last-y stop-y) 
:; Draw a line 

do (send *dest* *:show-11nes start-x (- start-y 12) 
(- end-x 1) stop-y) 
; Draw a second line. The two lines are a refinement 
; to stagger the endpolnts of the lines so the diagonal 
; edge looks neat, 
(send *dest* *: show- lines start-x (- start-y 12 1) 
(- end-x 1 1) stop-y))) 



The remaining functions (fr*aw and stripe one of the small arrows 

Function controlling drawing of a small arrow. 

Calculates coordinates of the arrowhead and outlines It. Binds x-coord 
of the projection of the last stripe onto the top edge. Calculates 
the horizontal distance between stripes. When necessary, stripes the 
head and shaft of the arrow, 
(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(multlple-value-blnd 
(•plx* 'ply* •p2x« •p2y» 'pSx* 'pSy* "pCx* 'pey*) 

( compute-arroti^ead-pol nts ) 
;; Outline the arrowhead 
(draw-outline) 
(when *do-the-str1pes* 

;; Bind x-coord of projection of last stripe onto top edge 
(let ((«x2* (- 'pOx* 'top-edge* *top-edge«)) 
;; Calculate distance between stripes 
(•str1pe-d* (compute-str1pe-d))) 
(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 

;;; Draws the outline of the head of a small arrow, 
(defun draw-outline () 
(send 'dest* *:show-11nes •p2x* •p2y* 'plx* 'ply* 
•pOx* 'pOy* 'pex* •p6y« 'pSx* 'pSy*)) 
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Function controlling striping of the shaft of a small arrow. 
Iterates over the descending triangles that make up the shaft. 
Calculates the coordinates of the top left and bottom right 
vertexes of each triangle. Finds the x-coord of the 
projection of the first stripe onto top edge. Calls 
DRAW-ARROW-SHAFT-STRIPES to stripe each triangle, 
(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Don*t exceed maximum 
;; recursion level. 

(loop for shaft-depth from 'depth* below 'max-depth* 
;: Calculate fractions of new top edge 
for top-edge-2 s «top-edge-2* then (// top-edge-2 2) 
for top-edge-4 » (// top-edge-2 2) 
;; Find coords of top left point of triangle 
for left-x s •p2x» then (- left-x top-edge-4) 
for top-y = •p2y» then (- top-y top-edge-2 top-edge-4) 
;; Find coords of bottom right point of triangle 
for right-x « (♦ left-x top-edge-2) 
for bottoffl-y » (- top-y top-edge-2) 

;; Find x-coord of projection of first stripe onto top edge 
for xoff = (- 'pOx* 'top-edge*) 
then (- xoff top-edge-2 top-edge-2) 
;; Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y right-x bottom-y xoff))) 

;; Stripes each triangle in the shaft of a small arrow. 
;; Arguments are coordinates of the top left and bottom right 
;; points of the triangle, and the x-coord of the projection 
;; of the first stripe onto top edge. Calculates the y-coord 
;; of the starting point and the x-coord of the ending point 
;; of each stripe. Finds number of lines in the stripe. Calls 
;; DRAW-ARROW-SHAFT-LINES to draw the lines in the stripe, 
(defun draw-arrow-shaft-stripes 

(left-x top-y right-x bottom-y xoff) 
;; Find y-coord of starting point of stripe. Don*t go 
;; be Tow the bottom of the triangle. 

(loop for start-y from top-y by 'stripe-d* above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x downfrom right-x by 'strlpe-d* 
;; Find number of lines in the stripe 
for n lines « (compute-n lines (- xoff (- right-x end-x))) 
;; Draw a stripe 
do (draw-arrow-shaft- lines 

nlines left-x start-y end-x bottom-y))) 
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Draws the lines In a stripe In the shaft of a small arrow. 
Arguments are the number of lines In the stripe and the 
coordinates of the starting and ending points of the first line, 
(defun draw-arrow-shaft- lines 

(nllnes left-x start-y end-x bottom-y) 
;; Set up a counter. Don*t exceed number of lines In the stripe, 
(loop for 1 from below nllnes 

;; Find x-coord of ending point of the line 
for last-x s (- end-x 1) 

;; Don*t go past the left edge of the triangle 
while (< left-x last-x) 
;; Draw a line 

do (send *dest* *: show- lines left-x (- start-y 1) 
last-x bottom-y))) 
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Appendix B 
Output Module for the Sample Program 



The program used as an example in this document draws the recursive arrow graphic on the 
docimient*s cover. This appendix contains Lisp code that defines the flavors and methods that 
mediate between the program and the system output operations. Appendix A (page 133) 
contains the code that calculates coordinates for the endpoints of the lin» that compose the 
figure. Appendix C (page 165) contains a reproduction of the LGP graphic the program 
produces. 

;;; -*- Node: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -*- 
;;; Copyright (c) 1983 Symbolics, Inc. 



#1 

This file contains the output module for a program that 
reproduces the recursive arrow graphic printed on the covers 
of most Symbolics documents. The module allows the graphic 
to be produced on a Lisp Nachlne screen, a Laser Graphics 
Printer, or an LGP record file. For each of these devices, 
the module produces output by sending appropriate messages 
with the coordinates of the endpoints of line segments to 
be dra%<n. This module receives these coordinates from a 
separate calculation module. 

For screen output, the module creates Its own windows. It 
defines a basic flavor of window that accepts point 
coordinates In the screen coordinate system, with origin 
at top left. It defines a more specialized window, built 
on the basic window, for use with a calculation module that 
uses LGP coordinates, with origin at bottom left. It 
allows a process to be associated with each window and 
lets users modify the characteristics of the figure. 

For LGP output, the module makes an Instance of a flavor 
with the output stream as an Instance variable. Output Is 
directed to either a hardcopy device or a record file. 

This module defines the top-level function, DO-ARROW, that 
Is called to produce the graphic. This function pops up 
a choose-varlable-values window to allow users to select the 
output device and the characteristics of the figure. The 
module defines conditions and handlers for attempts to give 
variables liqsermlsslble values. 
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This nodule determines the size of the figure and Its 
position within the page or window. It then calls the 
function ORAW-ARROW-GRAPHIC in the calculation nodule. 
It passes as arguments the length of the top edge of the 
figure and the coordinates of the top right point. The 
calculation module sends : SHOW- LINES messages to instances 
of output flavors. The arguments to :SHOW-LINES are the 
coordinates of the endpolnts of lines to be drawn. The 
current instance of the output flavor is the value of the 
special variable 'DEST*. 
I# 



;;; Following are declarations for special variables 

(defvar •dest- string* "Screen" 

"Destination of program output [Screen, LGP. or File]") 

(defvar •output-file* nil 
"Pathname for LGP-record-flle output") 

(defvar *f 111 -proportion* 0.9 
"Proportion of smaller dimension to be filled by figure") 



;;; The following flavor and Its methods are common to both 
;;; screen and LGP output 

(defflavor arrow-parameter-mlxin 

(width height top-edge right-x top-y) 
() 

(:gettab1e-1nstance-var1ab1es top-edge rIght-x top-y) 

( : required-methods :cofflpute-w1dth-and-he1ght) 

( :documentat1on :m1x1n 

"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; and coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering it within the page or window and making it fill no 
more than the specified proportion of the smller dimension. 
The methods use a coordinate system with origin at bottom left; 
other mix Ins must correct for this if output is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed into any Instantlable flavor that produces output for the 
arrow graphic.")) 
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;;; Method controlling calculation of size and position of figure. 
;;; Sends messages to self to calculate width and height of page 
;;; or window, length of top edge of figure, and coordinates of 
;;; f1gure*s top right point. These are separate nethods so that 
;;; other flavors can shadow then or add daemons. Another flavor 
;;; must provide a method to compute width and height, because 
;;; this Is specific to the output device, 
(defmethod (arrow-parameter-mix In : compute-parameters) () 

;; Another flavor must supply method for width and height 

(send self *:compute-w1dth-and-he1ght) 

;; Make a preliminary estimate of length of top edge 

(send self *: confute- top-edge) 

;; Adjust top edge to make It a mltlple of 128 

(send self *: ad Just-top-edge) 

;; Calculate coordinates of top right point of figure. 

;; We can*t do this until we know how long top edge Is. 

(send self *:corapute-r1ght-x) 

(send self ': compute- top-y)) 

;;; Makes a preliminary estimate of length of top edge. 
;;; The top edge of the arrow Is 80 percent of the horizontal 
;;; or vertical length of the whole figure. First finds the 
;;; smaller of the length or width of the page or window. 
;;; Multiplies this by the proportion of this dimension that 
;;; Is to be filled by the figure. The result Is the 
;;; horizontal or vertical length of the figure. Multiplies 
;;; this by 0.8 to get the length of the top edge, 
(defmethod (arrow-parameter-mlxln : compute- top-edge) () 
(setq top-edge 

(fixr (• 0.8 •fill-proportion* (min width height))))) 

;:; Adjusts length of top edge so It Is a multiple of 128. 
;;; There are 64 stripes In the head of the large arrow. The 
;;; calculation module divides the length of top edge by two 
;;; each time It goes down another recursion level. By making 
;;; the original top edge a multiple of 128, we maximize 
;;; continuity In striping between arrowheads and shafts and 
;;; among the first several levels of recursion, 
(defmethod (arrow-parameter-mlxln :adJust-top-edge) () 
(setq top-edge 

;; Minimum length of top edge Is 128 
(If « top-edge 256) 128 

;; Otherwise set to next lower multiple of 128 
(• 128 (fix (// top-edge 128)))))) 

;;; Calculates x-coordlnate of top right point of figure. 
:;; Finds horizontal length of figure by dividing length of 
;;; top edge by 0.8. Centers the figure horizontally within 
;;: the page or window. 

(defmethod (arrow-parameter-mlxln :compute-r1ght-x) () 
(setq right-x 

(fixr (• 0.5 (♦ width (// top-edge 0.8)))))) 
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;;; Calculates y-coordlnata of top r1(^t point of figure. 
;;; Assuaes that the origin Is at bottom. Finds vertical 
;;; length of figure by dividing length of top edge by 0.8. 
;;; Centers the figure vertically within the page or window, 
(defnethod (arrow-paraneter-alxin :conpute-top-y} () 
(setq top-y 

(fixr (• 0.5 (♦ height (// top-edge 0.8)))))) 



;;; Following are flavors and nethods for screen output 

(def flavor baslc-arrow-wlndow-alxin 

(do-stripes max-dep fill-prop) 
() 

: Inltable-lnstance-varlables 

(: required-flavors arrow-parameter-nlxln tv:w1ndow) 

(:defau1t-1n1t-p11st 
:edges-froa *:nouse rnlnlnum-wldth 200 :n1nlMua-he1ght 200 
:b11nlcer-p nil :expose-p t) 

( :docuaentat1on :n1x1n 

"Provides for a basic window to display the arrow graphic. 
ARROW-PARAHETER-NIXIN Is needed to position the figure within 
the window. Instance variables hold values for mxIrum 
recursion level, proportion of window to be filled, and 
whether or not to stripe the figure. This flavor assumes 
window coordinates, with origin at top left. It provides Its 
own :COHPUTE-TOP-Y method to use that origin. It provides a 
method to find the width and height of the window, as 
ARROW-PARANETER-NIXIN requires. This flavor has a :SHOW-LINES 
method to receive point coordinates from the calculation 
module and draw lines on the window. It provides a :NAIN-LOOP 
method so that the window can run in Its own process and Tet 
the user modify the graphic. TV:LIST-NOUSE-BUTTONS-HIXIN Is 
needed to handle mouse clicks If this method Is used. This 
flavor provides standard :AFTER daemons for the window-system 
:INIT, : REFRESH, and :CHANGE-OF-SIZE-OR-HARGINS messages. This 
flavor should be mixed In with ARROW- PARAMETER-HIXIN and 
TV:WINDOW for any window that produces the graphic. It 
should be Included before ARROW-PARANETER-NIXIN so that the 
:COMPUTE-TOP-Y method shadows correctly.')) 
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Receives endpoint coordinates and draws lines on a window. 
Arguments are alternating x- and y-coordlnates of the end- 
points of lines to be drawn. If there are more than two pairs 
of coordinates, assumes that the endpoint of one line Is the 
starting point of the next. Sends messages for separate methods 
to determine the actual coordinates. This Is so that other 
flavors can modify the coordinates. Draws a line by sending self 
a : DRAW- LINE message, and so assumes that TV:GRAPHICS-MIXIN Is 
Included somewhere to provide this method, 
(defmethod (baslc-arrow-wlndow-mlxin :show-11nes) 
(x y &rest x-y-pairs) 
; First determine the starting point of the line. On 
; subsequent trips through the loop, the last endpoint 
; becomes the next starting point, 
(loop for xO s (send self *:coii9ute-x x) then xl 
for yO « (send self 'tcompute-y y) then yl 
;; "Cddr" down the list created by making all but the 
;; first pair of coordinates an &rest argument 
for (xl yl) on x-y-paIrs by #*cddr 
;; Determine the endpoint of the line 
do (setq xl (send self *:compute-x xl) 
yl (send self *:compute-y yl)) 
;; Draw the line 
(send self *:draw-11ne 

xO yO xl yl tv:alu-1or t))) 

; Determines the x-coordlnate of an endpoint of a line. 
; This Is a separate method so that other flavors can shadow 
: It or add daemons to manipulate the coordinate, 
(defmethod (baslc-arrow-wlndow-mlxin :compute-x) (x) 
(fixr X)) 
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; Deternlnes the y-coordlnate of an endpoint of a line. 
; Assunes that the argunent already uses window coordinates, 
; with origin at top left. This Is a separate nethod so that 
; other flavors can shadow It or add daemons to Manipulate 
; the coordinate, 
(defnethod (baslc-arrow-wlndow-nlxin :compute-y) (y) 
(fixr y)) 

Finds the Inside width and height of the window. 
Sends self an : INSIDE-SIZE nessage, and so assunes that 
TV:NININUH-WINDOW Is Included somewhere to provide this 
method, 
(defmethod (baslc-arrow-wlndow-mlxin 

:compute-w1dth-and-he1ght) () 
(multiple-value (width height) 
(send self *: Inside-size))) 

; Calculates y-coordlnate of top right point of figure. 
; Finds vertical length of the figure by dividing the length 
; of top edge by 0.8. Centers the figure vertically within 
; the window. Gives the result In window coordinates, with 
; origin at top left. This method shadows that In 
; ARROW-PARAHETER-NIXIN. 
(defmethod (baslc-arrow-wlndow-mlxin :compute-top-y) () 
(setq top-y 

(fixr (• 0.5 (- height (// top-edge 0.8)))))) 

Calculates size and position of figure after Initialization. 
Binds the global variable •fill-proportion* to the value of 
the corresponding Instance variable so that the figure will 
be drawn correctly If the value of •f111-proport1on« has 
changed. 

(defmethod (baslc-arrow-wlndow-mlxin : after :1n1t) (Ignore) 
(let ((•fill-proportion* fill-prop)) 
(send self *: compute-parameters))) 

Calculates size and position of figure after window change. 
Binds the global variable *f111-proport1on* to the value of 
the corresponding Instance variable so that the figure will 
be drawn correctly If the value of *f111-proport1on* has 
changed, 
(defmethod (baslc-arrow-wlndow-mlxin 

:after :change-of-s1ze-or-marg1ns) (&rest Ignore) 
(let ((*f Ill-proportion* fill-prop)) 
(send self *:compute-parameters))) 



Pro gram Development Tools and Techniques ] £££ 

Symbolics, Inc. 



Draws the figure when necessary after window Is refreshed. 
Binds the global variable «dest« to self and the variables 
«do-the-str1pes* and •max-depth* to the corresponding Instance 
variables so the figure will be drawn correctly If the values 
,,, of the global variables have changed, 
(defnethod (bas1c-arrow-w1ndow-«1x1n rafter :refresh) 
(&opt1ona1 type) 
;; Draw figure If not restored from a bit-save array ... 
(v^en (or (not tv:restored-b1ts-p) 

;; ... or size has changed ... 
(eq type *: size-changed) 
;; ... or new values for figure parameters, 
(eq type 'tnew-vals)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-b1ts-p 

(send self ': clear-screen)) 
;; Bind global variables to self and Instance variables 
(let ((«dest« self) 

(*do-the-str1pes« do-stripes) 
(•max-depth* max-dep)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 

Provides a mouse documentation line for the window. 
The only option Is to click right and pop up a 
choose-variable-values window of options for changing 
the graphic on this window. 
( def method ( bas 1 c-arrow-wi ndow-mix 1 n 

:who-11ne-documentat1on-str1ng) () 
■R: Choose-variable-values options for changing figure on this window") 
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CoMMnd loop for window associated with a separate process. 
Consists of an error-restart- loop that handles restarts fro» 
errors and sys:abort. Walts for nouse Input. If a right 
click, pops up a choose-varlable-values window to change 
characteristics of the figure. On exit, sets Instance variables 
to the new values and refreshes the window, then waits for another 
nouse click. Assumes blips are lists of the forn provided 
by TViLIST-HOUSE-BUTTOHS-HIXIM. 
(defMethod (baslc-arrow-wlndow-nlxln :iia1n-loop) () 

;; Run forever In a loop. Offer a restart handler If an error 
;; or sys:abort Is signalled. 

(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
;; Walt for Input 

(let ((char (send self *:any-ty1))) 
;; Pop up window If Input Is a list ... 
(when (and (llstp char) 

;; ... and a mouse click ... 
(eq (first char) *:mouse-button) 
;; ... and a single click on the right button, 
(eq (second char) #\mouse-r-l)) 
;; Bind global variables to Instance-variable values 
(let ((*do-the-str1pes« do-stripes) 
(•max-depth« max-dep) 
(•fill-proportion* fill-prop)) 
;; Pop up a choose-varlable-values window 
(tv:choose-var1able-values 
*((*do-the-str1pes« "Stripe the arrows?" :boolean) 
(•max-depth* "Number of recursion levels" :number) 
( 'f 1 1 1 -proportion* 
"Fraction of window to be filled" :number)) 
;; Make the window wide to provide enough rora for error 
;; ■rassages. 
*: extra-width 20 

;; Call a function to check for errors when values change 
*:funct1on *check-1tem 
;; Give the user a chance to abort 

• :marg1n-cho1ces '("Do It" ("Abort" (signal 'sysrabort))) 
*: label "Choose Options for Graphic") 
:; Set instance variables to the new values 
(setq do-stripes *do-the-str1pes« 
max-dep •max-depth* 
fill-prop *f111-proport1on*) 
;; Recompute size and position of the figure 
(send self *: compute-parameters) 

;; Send : REFRESH message with argument of *:new-vals to make 
;; sure the figure Is redrawn If there is a bit-save array 
(send self 'irefresh *:new-va1s)))))) 
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(def flavor basic-arrow-window () 

(baslc-arrow-wlndow-nlxln 

arrow-paramoter-BlxIn 

tv:any-ty1-n1x1n 

tv:11$t-Biouse-button$-«1x1n 

tv:process-iii1x1n 

tv: window) 
(: documentation :comb1nat1on 
"Instantlable flavor providing a basic window for output. 
Though this flavor Is Instantlable, Its methods assume that 
point coordinates use the window coordinate system, with 
origin at top left. To *«)rk with the current calculation 
module It needs another mixin to convert LGP to screen 
coordinates. In the component flavors, BASIC-ARROW-WIMDOW-HIXIM 
must come before ARROW- PARAMETER-MIXIH and TV:WINDOW for 
shadowing and daemons to work correctly. TV:PROCESS-MIXIM 
and TV:LIST-MOUSE-BUTTOMS-MIXIH are not necessary unless the 
window Is associated with a separate process and the :HAIM-LOOP 
method of BASIC-ARROW-WINDOW-NIXIN Is the command loop.")) 



(defflavor Igp-wlndow-mlxin 
((scale-factor 2.5)) 

() 
( : required-flavors basic-arrow-window) 

(: documentation :m1x1n 
"Converts LGP to screen coordinates and vice versa. 
When mixed In with BASIC-ARROW-WIMDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The Instance variable SCALE-FACTOR Is the 
ratio of LGP to screen pixel density. The methods take 
the height and width of the window In screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure In LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those In 
ARROW-PARAMETER-HIXIH and BASIC-ARROW-WINDOW-HIXIH.")) 



Converts x-coord of line endpoint from LGP to screen pixels. 
Corrects for higher density of LGP pixels. This method shadows 
that of BASIC-ARROW-WINDOW-NIXIN. 
(defmethod (Igp-wlndow-mlxin :c(»ipute-x) (x) 
(fixr (// X scale-factor))) 



, > > 



;;; Converts y-coord of line endpoint from LGP to screen pixels. 
;;; Corrects for higher density of LGP pixels and for screen origin 
:;; at top left. This method shadows that of BASIC-ARROW-WINDOW-MIXIN , 
(defmethod (Igp-wlndow-mlxin :compute-y) (y) 
(fixr (- height (// y scale-factor)))) 
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;; Calculates top edge In LGP pixels fron screen proportions. 
;; Nultlplles length of smaller dlmenslo*. In screen pixels, by 
;; proportion of this dimension to be filled by the figure. 
;; Multiplies this by 0.8 to find top edge In screen pixels. 
;; Corrects for higher density of LGP pixels. This method 
;; shadows that of ARROW- PARAMETER-HIXIN. 
(defmethod (Igp-wlndow-mlxin zcmnpute- top-edge) () 
(setq top-edge 

(fixr (• scale-factor 0.8 'fill-proportion* 
(mln width height))))) 

Calculates x-coord of top right point In LGP pixels. 
Finds horizontal length of figure In screen pixels by 
dividing top edge by 0.8. Centers figure horizontally 
1n window, correcting for higher density of LGP pixels. 
This method shadows that of ARROW- PARAHETER-HIXIN. 
(defmethod (Igp-wlndow-mlxin :compute-r1ght-x) () 
(setq right-x 

(fixr (• 0.5 (♦ (• width scale-factor) 
(// top-edge 0.8)))))) 

Calculates y-coord of top right point In LGP pixels. 
Finds vertical length of figure In screen pixels by 
dividing top edge by 0.8. Centers figure vertically 
In window, correcting for higher density of LGP plxeVs. 
This method shadows those of ARROW- PARAMETER-HIXIN and 
BASIC-ARROW-WINDOW-NIXIN . 
(defmethod (Igp-wlndow-mlxin :compute-top-y) () 
(setq top-y 

(fixr (• 0.5 (♦ (• height scale-factor) 
(// top-edge 0.8)))))) 



(defflavor arrow-window () 

( Igp-wlndow-mlxin basic-arrow-window) 
( :documentat1on tcomblnatlon 
"Instant labia flavor for window output from LGP coordinates. 
This flavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
Is the flavor to Instantiate for window output using the 
current calculation module.")) 
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;;; The following flavor and methods are for LGP output 

(defflavor 1gp-p1xe1-m1x1n 
(output-stream) 

() 

: Inltable-lnstance-varlables 

( : required-flavors arroM-parameter-mlxin) 

(: documentation :m1x1n 
"Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAKETER-NIXIN is required to calculate the size of the 
figure and position It In the center of the page. This flavor 
has a method to calculate the width and height of the page, as 
ARROW-PARANETER-MIXIN requires. It has a :SHOW-LINES method to 
receive point coordinates from the calculation module and draw 
lines on the output stream. The method assumes that coordinates 
are In LGP pixels. The method also assumes that flavor 
LGP:BASIC-LGP-STREAN Is Included In output stream to provide 
:SEND-COHMAND and :SEND-COORDINATES messages. This flavor 
should be mixed, along with ARROW- PARAHETER-NIXIN, into an 
Instantlable flavor for LGP output. When that flavor Is 
Instantiated, the Instance variable output-stream should be 
Initialized.")) 



Receives endpoint coordinates and draws lines on LGP stream. 
Arguments are alternating x- and y-coordlnates of endpolnts of 
lines to be drawn. If there are more than two pairs of 
coordinates, assumes that the endpoint of one line is the 
starting point of the next. Draws a line by sending output 
stream :SEND-COHHAND messages for LGP connands and 
:SEND-COORDINATE messages for LGP coordinates. Assumes that 
flavor LGP: BASIC -LGP-STREAM is Included In output stream to 
provide these methods, 
(defmethod (Igp-plxel-mlxin :show-11nes) 
(xO yO &rest x-y-pairs) 
;; Send command and coordinates to start drawing lines 
(send self *:send-cofflmand-and-coord1 nates #/m xO yO) 
;; "Cddr* down the list created by making all but the first 
;; pair of coordinates an &rest argument 
(loop for (x y) on x-y-paIrs by #*cddr 

;; Send command and coordinates to draw a line 

do (send self *:send-cofflmand-and-coord1 nates #/v x y))) 

Sends line-drawing commands to LGP output stream. 

tSEND-CONHAND transmits an LGP command. :SEND-COOROINATES 

transmits coordinates of an endpoint of a line to be drawn. 

Assumes that LGP:BASIC-LGP-STREAM Is included In output stream 

to provide these methods, 
(defmethod (Igp-plxel-mlxin :send-conmand-and-coord1nates) (cmd x y) 
(send output-stream *:send-command cmd) 
(send output-stream *:send-coord1 nates (fixr x) (fixr y))) 
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Finds width and height of a page for LGP output. 
This flavor Is required by ARROW-PARAHETER-NIXIN. Finds the 
values of' two instance variables of LGP: BASIC- LGP-STREAM: 
SI: PAGE-WIDTH and SI: PAGE-HEIGHT. Assumes that 
LGP:BASIC-LGP-STREAN Is Included In output streaa to provide 
these Instance variables, 
(defnethod (Igp-plxel-nlxin :coiipute-w1dth-and-he1ght) () 
(setq width (symeval- In- Instance output-streaa *s1:page-w1dth) 

height (syneval- In- Instance output-streaa *s1:page-he1ght))) 



(defflavor 1(H>~p1xe1 -streaa () 

( Igp-plxel-alxin arrow-paraneter-alxin) 
( :docuaentat1on :coab1nat1on 
"Instantlable flavor for arrow output on LGP streaa. 
Assuaes that the calculation aodule uses LGP coordinates. 
When this flavor Is Instantiated, the LGP-PIXEL-NIXIN 
Instance varlabTe OUTPUT-STREAM should be Initialized. 
The output streaa can be directed to an LGP or a file, 
but It aust Include flavor LGP:BASIC-LGP-STREAN for 
output to work correctly.*)) 



;;; Following are condition flavors for bad variable values 

(defflavor bad-arrow-varlable () (error) 
( :documentat1on 

"Hon Instant labia class of bad-variable conditions. 
The user alght set soae variables to laperalsslble values. 
These conditions are to peralt checking for bad values 
beyond the systea*s error checking. Instantlable condition 
flavors for specific variables should be built on this 
flavor.-)) 



(defflavor bad-arrow-depth () (bad-arrow-varlable) 
( :documentat1on 

"Proceedable condition: bad value for •MAX-DEPTH*. 
An Instantlable condition flavor for Impermissible values 
of •MAX-DEPTH*, the nuaber of recursion levels In the 
figure.")) 

;;; Prints string on streaa to report bad *MAX-DEPTH* value 
(def method (bad-arrow-depth : report) (stream) 
(format stream "No. of levels was not a " 
nonnegatlve fixnum.")) 
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;;; Proceed type nethod for supplying new value of «HAX-DEPTH« 
(def method (bad-arrow-depth tease : proceed : new-depth) 
(^optional (dep (pronpt-and-read 
*: number 

"Supply new value for " 
no. of recursion levels: ■))) 
■Supply a new value for number of recursion levels." 
(values *:new-depth dep)) 



(defflavor bad-arrow-flll-proportlon () (bad-arrow-varlable) 
(: documentation 
"Proceedable condition: bad value for «FILL-PROP(»TIOH«. 
An Instantlable condition flavor for Impermissible values of 
•FILL-PROPORTIOM*, the fraction of the smaller dimension of 
the page or window that the figure Is to fill.')) 

;;; Prints string on stream to report bad «FILL-PROPORTION« value, 
(defmethod (bad-arrow-flll-proportlon :report) (stream) 
(format stream "Proportion was not a fraction between " 
and 1.")) 

; ; ; Proceed type method for new value of «FILL-PROPORTION« 
(defmethod (bad-arrow-flll-proportlon :case :proceed 

:new-proport1on) 
(&opt1onal (prop (pronpt-and-read 
*:nunrt)er 

"Supply new fraction of bounds -' 
be filled: "))) 
"Supply a new fraction of page or window to be filled." 
(values *:new-proport1on prop)) 
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;;; Top-level function 

Top-level function to call to produce arrow graphic. 
Pops up a choose-varl able- values window to let user specify 
output destination, number of recursion levels, proportion 
of srnller dimension of page or window to be filled, and 
whether or not to stripe figure. If screen output, makes a 
window. If LGP output, makes an LGP stream and calls 
DRAW-ARROW-GRAPHIC to draw the figure, 
(defun do-arrow () 

;; Pop up a choose-varlable-values window 
( tv : choose- var 1 ab 1 e- va 1 ues 

*((*do-the-str1pes* "Stripe the arrows?" :boolean) 

(*max-depth* "Number of recursion levels" :number) 

(•fill-proportion* 
"Fraction of page or window to be filled" tnumber) 

(*dest-str1ng« "Output destination" 

:choose ("Screen" "LGP" "File")) 

(•output-file* "Pathname for file output" :pathname)) 
; ; Make window wide enough to acconnodate long pathnames 
;; and error messages 
*:extra-w1dth 20. 

;; Call this function when a value Is changed 
*:funct1on *check-1tem 
;; Give user a chance to abort 

*:marg1n-cho1ces '("Do It" ("Abort" (signal *sys:abort))) 
*: label "Choose Options for Graphic") 
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;; If figure Is Infinitely small, just return nil 
(cond ((« *fni -proportion* 0) nil) 

;; If screen output, make a window 
((equal "dest-strlng* "Screen") 
(tv:make-w1ndow 'arrow-window 

;; Initialize Instance variables to 
;; values set by the user 
♦ : do-stripes •do-the-stripes* 
*:inax-dep •nax-depth* 
•:f Ill-prop •fill-proportion* 
;; Specify top-level function for the 
;; process associated with the window 
*: process '(window-loop))) 
;; If LGP or file output, use an appropriate stream 
(t (with-open-stream 
(stream 

;; This function returns a stream suitable for 

;; LGP output 

(si :make-hardcopy-stream 

;; Argument Is the output device. For LGP, 
;; use the default hardcopy device, 
(if (equal •dest-string* "Igp") 
si :«default-hardcopy-dev1ce« 
;; For file output, use the correct format 
;; for the hardcopy device and direct 
;; output to the file specified by the user 
(lgp:get-lgp-record-f11e-hardcopy-device 
•output-file*)))) 
;; Hake an Instance of our LGP output flavor 
(let ((•dest^ 

(make-instance Mgp-plxel -stream 

;; Initialize Instance 
;; variable to output stream 
*: output-stream stream))) 
;; Position the figure oh the page 
(send 'dest^ *: compute-parameters) 
;; Draw the figure, using instance-variable values 
;; as arguments 

(draw-arrow-graphic (send "dest^ 'ttop-edge) 
(send "dest^ 'iright-x) 
(send •dest^ 'itop-y))))))) 



Top-level function for process associated with arrow window. 
The function Is called when the window is created. Argument is 
the window. The function sends the window a :MAIM-LOOP message. 
This method should be the actual command loop for the process, 
(defun window- loop (window) 
(send window *:ma1n-loop)) 
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Function to check variable values 

Called when a value changes In choose-varlable-values window. 
Argunents are the window, the variable, and Its old andnew values. 
Binds handlers for conditions for livemlsslble values. If new 
value Is OK, sets variable to the new value, refreshes window, and 
returns t. If value Is not OK, signals the appropriate condition. 
When SIGNAL returns, presumably with a new variable value, checks 
the new value In the sane way It checks a new value that comes 
from the window, 
(defun check-Item (cw-wlndow var old-val new-val) 

;; We don't use the old value. To avoid a compiler complaint, 
;; Just evaluate It and Ignore It. We could also use IGNORE 
;; Instead of OLD-VAL In the argllst, but then the argil st 
;; would be less meaningful, 
old-val 

;; Bind handlers for the conditions we might signal 
(condition-bind ((bad-arrow-depth *bad-arrow-var-hand1er) 
(bad-arrow-flll-proportlon 
*bad-arrow-var-hand1er) ) 
(when (eq var **max-depth*) 

;; •MAX-DEPTH* must be nonnegatlve fixnum 
(loop until (and (fixp new-val) (i new-val 0)) 

If It's not, bind QUERY- 10 to the window and 
signal a condition. SIGNAL should return 
two values, the proceed type and the new 
value from the proceed method. Ignore the 
proceed type and set NEW-VAL to the new 
value, 
do (let (( query- 1o cw-w1ndow)) 

(multiple-value (nil new-val) 
(signal * bad-arrow-depth))))) 
(when (eq var **f111-proport1on*) 

;; •FILL-PROPORTION* must be between and 1 
(loop until (and (i new-val 0) (i new-val 1)) 

If It's not, bind QUERY- 10 to the window and 
signal a condition. SIGNAL should return 
two values, the proceed type and the new 
value from the proceed method. Ignore the 
proceed type and set NEW-VAL to the new 
value, 
do (let (( query- 1o cw-wlndow)) 
(multiple-value (nil new-val) 
(signal 'bad-arrow-f 1 1 1 -proportion ) ) ) ) ) 
;; Variable value is now OK. Set variable to the new value. 
;; Note that we DO want to evaluate VAR. 
(set var new-val) 
;; Refresh the window 
(send cw-wlndow ':refresh) 
;; Return t 
t)) 
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Handler for bad-varlable-vaTue conditions 

Handler for bad value of •HAX-DEPTH* or •FILL-PROPORTIOH*. 
Argument Is the condition object created by SIGNAL. Uses QUERY-IO 
stream to report condition. Sends the condition object a : PROCEED 
message and passes back the values It returns, 
(defun bad-arrow-var-handler (cond-obj &aux bl) 

;: Find out whether this object has the right proceed type. 

;; If not, return nil. 

(If (send cond-obJ »: proceed- type-p 

(cond ((typep cond-obJ ♦ bad-arrow-depth) »:new-depth) 
((typep cond-obJ 'bad-arrow-f 111 -proportion) 
* : new-proportion ) ) ) 
;; Enclose the handling operation In an UNWIND-PROTECT so that 
;; If tra use a blinker tra are sure to turn It off 
(unwind-protect 
(progn 

;; Use a blinker If the QUERY-IO stream is a window 
(setq bl (If (typep query- 1o *tv: sheet) 

;; If a cursor-following blinker exists, use It 
(or (tv:sheet-follow1ng-bl1nker query-lo) 
;; Otherwise, make a new blinker 
(tv:make-bl Inker query-lo 

*tv:rectangular-bl Inker 
•:follow-p t)))) 
;; If a blinker, make It blink 
(If bl (send bl ♦:set-v1s1b111ty ':bl1nk)) 
;; Alert the user 
(tv:beep) 

;; Send a report, presumably describing the condition 
(send cond-obJ ': report query-lo) 

;; Send object a : PROCEED message and return the values 
;; that the method returns 
(send cond-obJ *: proceed 

(cond ((typep cond-obJ * bad-arrow-depth) •:new-depth) 
((typep cond-obJ 'bad-arrow-f Ill-proportion) 
• : new-propor t 1 on ) ) ) ) 
;; If a blinker, turn It off 
(If bl (send bl • -.set-visibility nil))))) 



This macro expression causes combined methods to be compiled at 
compile time and data structures to be generated at load time. 
Otherwise, these things happen at run time, vfhen the first 
Instance of a flavor Is made, 
(complle-flavor-methods arrow-window Igp-plxel -stream 

bad-arrow-depth bad-arrow-f 1 1 1 -proportion ) 
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Appendix C 
Graphic Output of the Sample Program 



The program used as an example in this document draws the recursive arrow graphic on the 
document's cover. This appendix contains a reproduction of the LGP graphic the program 
produces. Appendix A (page 133) contains Lisp code that calculates coordinates for the 
endpoints of the lines that compose the figure. Appendix B (page 147) contains the code that 
defines the flavors and methods that mediate between the program and the system output 
operations. 
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:draw-liBC; Method for tvigrapldcf-Bixia 1 1. 106 

»d(ef-froai, Init Option to tTnaiaianua-wuklow 106 

[Edit] 7,74 

Edit Callers (a-x) 37 

Edit Changed Definitions (m-x) 49 

Edit Changed Definitions Of Buffer (m-x) 49 

Edit Combined Methods (m-x) 1 3 1 

Edit Compiler Warnings (m-x) 73 

Edit Definition (m- .) 33, 128, 129 

Edit Methods (m-x) 57,131 

[Edit Screen] 58,121 

Electric Shift Lock Mode (m-x) 10 

END 6 

End Kbd Macro (c-x )) 56 

mitry. Option to trace 87 

mitrycoiid. Option to trace 87 

rcatrjrpriat, Cation to trace 87 

[Error] 87,90 

error. Flavor 122 

»rror, Cation to trace 87, 91 

cmNr-rcstart-looft Macro 119 

Evaluate And Replace Into Buffer (m-x) 68 

Evaluate Buffer (m-x) 68 

Evaluate Changed Definitions (m-x) 68 

Evaluate Changed Definitions Of Buffer (m-sh-E) 68 

Evaluate Into Buffer (m-x) 68 

Evaluate Minibuffer (m-ESCAPE) 68 
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Evaluate Region (e-sh-E) 68 

Evaluating code 61, 66, 86 

[Exit] 94 

texit Option to trace 87 

:exitbreak. Option to trace 87, 91 

:exitcoiid, Option to trace 87 

texitprint Option to trace 87 

Expanding macros 91 

texpoce-p, Init Option to tyMiamma-wMdow 106 

Files 

Attribute lists 7 

Copying 55 

Creating 7 

Directories 37 

Init 9, 56 
Fill Long Comment (m-x) 20 
Find File (c-x c-f) 7 
Find Unbalanced Parentl»ses (a-x) 22 
flaTor-aUowed-iait-key wonhk Function (in package si:) 

131 
Flavors 

coaditicNi 122 

error 122 

lgp:basic>lfp-<treaiB 112.113 

si:Tanilla-flavor 129 

SyKafcort 119 

tvuuiy-tyi-auxia 118 

tir:srapldc9-BixiB 106 

tT:list4BOiise-t»cittOBfHBixia 118 

tTtpiakitti-WMdoir 107 

tT:proceflf-adxia 118 

tT»beet 127 

UiwvaiS&m 102. 105. 106. 107 
Function Apropos (n-x) 34 
:fiuctioa, ^tion to tr^kooee-TariaUc-Talaca 121 
Functions 33 

apropos 31 

arglift 36 

kreakoB 90 

Compiled 61 

conpilerxcoaipile-file 65 

coBpiler:coBpile-flle>load 66 

dbg 90 

describe 28,30.94 

descriW-flavOT 129 

disasseMUe 94, 97 

dociuKBtatioa 32, 36 

get-kandler-for 131 

iaspcct 97 

Interpreted 61 

listarray 30 

load 66 

BUtke-systca 71 

■exp 94 

pkg-foto 17 



plist 32 

pr<HBpt-aBd-read 126 
si:flavor-alIoired-iait-key words 131 
si:iBake-lardcopy-streaa 116 
signal 102.123,126 
step 89 

trrchoose-TariaUe-Talnes 114, 121 
tT»ake-Uiid[er 127 
traiake-iriBdoir 102, 1 12, 1 1 5, 1 1 8 
trvbeet-foUowiBg-Uiiawr 127 
typep 129 
lubreakoB 90 
what-nies-caU 32 
where-is 31 
irho<alls 32 

G«ieric operations 102 
get-haadler-for, function 131 
tgettaUe-iostaace-TariaMei; Option to defflavor 103 
graphicsHuxia, Flavor (in package tr:) 106 

HELP 5. 6. 56. 86 

Incremental Search (c-s) 50 

Indent For Comment (c- ; or m- :) 20 

Indent For Lisp (tas or e-»-TAB) 2 1 

Indent New Comment Line (n-LiNE) 20 

Indent New Line (line) 21 

Indent Region (cHi-\) 21 

Indent Sexp (e-n-Q) 21 

Init files 9.56 

Init keywords (for flavors) 131 

:iut Method for tT»keet 109 

Init Options 
:bliBker>p to tTnainiBiuB-wMidow 106 
;edges-f Hwa to tvcwlBlaiBi-wiadow 106 
:cxpose-p to traaiaiBUB-wiadow 106 
aaiaimwa-keight to tvaniauBiiai-wiadow 106 
auaiawB-width to trnaiaiaiiuB-wiadow 106 
tproccss to tv:proccs»«ixiB 1 1 8 

daitaUc-iastaace-TariaUci; Option to deffiavor 1 12. 
115 

Insert Buffer (m-x) 56 

Insert File (n*x) 56 

daside-dzc; Method for tTauaiaiiuB-wiBdow 107 

[Inspect] 97 

laspect Function 97 

Inspector 94, 128 

Install Macro («-x) 56 

Install Mouse Macro (n-x) 56 

Instance variables 103, 1 12. 1 1 5 

Interpreted functions 61 

Jump To Saved Position (c-x j) 52 
Keyboard macros 56 
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Kill Comment (chu- ;) 
Kill Sexp (cHK-K) 54 
Killing text 52 



20 



lgp:Vasic-Igp-ctreaa. Flavor 1 12. 1 13 
lgp:l»asic-lgp-ctre«B Methods 

xcend-coBBUUid 113 

neBd-coordinatet 1 1 3 

LINE (Indent New Line) 21 
Lisp input editing 68 
Lbp input editor commands 

c-C 69 

»-C 69 
Lisp Mode (m-x) 10 
Lbt Callers (m-x) 31.37 
List Changed Definitions (n-x) 49 
Lbt Changed Definitions Of Buffer (n-x) 49 
List Combined Methods (m-x) 1 3 1 
List Matching Lines (m-x) 50 
List Matching Symbob (m-x) 32 
Lbt Methods (n-x) 130 

list-aioa«e-batt<MS-BUxi% Flavor (in package tr:) 118 
listarray. Function 30 
Load Compiler Warnings (m-x) 73 
Load File (m-x) 66 
load. Function 66 
Long Documentation (M-ah-o) 32, 36 

M-X (Query Replace) 5 1 

M- . (Edit Definition) 33. 128, 129 

M- : (Indent For Comment) 20 

M-B (Debugger command) 75 

M-c (Lbp input editor command) 69 

M-ESCAPE (Evaluate Minibuffer) 68 

M-L (Debugger command) 75 

M-LINE (Indent New Comment Line) 20 

M-N (Down Comment Line) 20 

M-P (Up Comment Line) 20 

M-sh-c (Compile Changed Definitions Of Buffer) 64 

M-sh-D (Long Documentation) 32. 36 

M-sh-E (Evaluate Changed Definitions Of Buffer) 68 

M-SPACE (Push Pop Point Explicit) 52 

M-w (Save Region) 54 

M-Y (Yank Pop) 54 

Macro Expand Expression (c-sh-M) 94 

Macro Expand Expression All (m-x) 94 

Macros 

compile-flavor-metliodt 128 

c<Niditi<Hi-¥uid 123 

defcoost 62 

defflavor 103. 106 

defsystm 51 

defvar 13,62 

def window-refonrce 1 1 5 

error-restart-loop 1 1 9 

Expanding 91 



Keyboard 56 

witkH»peB-ftreaa 116 
■ake-bliaker. Function (in package tr:) 127 
■uke-hardcopy-ctrean. Function (in package si:) 116 
■uke-fysteai, Function 71 
■ake-systea Options 

:batch 71 
■ake-wiadow. Function (in package tv:) 102, 1 12, 115, 

118 
Mark Definition (c-m-h) 54 
Mark Whole (c-x h) 56 
Menu items 

[ARGPDL] 86 

[Attributes] 128 

[Break after] 86 

[Break before] 86 

[Cond after] 86 

[Cond before] 86 

[Cond break after] 86, 91 

[Cond break before] 86,91 

[Conditional] 86 

[Edit Screen] 58, 121 

[Edit] 7,74 

[Error] 86,90 

[Exit] 94 

[Inspect] 97 

[Modify] 95 

[Print after] 86 

[Print before] 86 

[Print] 86 

[Retry] 74 

[Return] 94,95 

[Split Screen] 58, 121 

[Step] 86.89 

[Trace] 85.89 

[Untrace] 86 

[Wherein] 86 
Method combination 

uuue 122 

rdaemoa 103. 106. 108. 109. 1 la 1 1 1 
Methods 129 

uuiy-tyi for triany-tyi-mixui 1 1 9 

tchange-of-size-or-aargias for tv^beet 109 

Daemon 108, 109 

tdraw-line for tvigraphics-aixia 11, 106 

:iait for tv:sheet 109 

:uside-size for tv»uBimuiii-iriiidow 107 

toperatioa-haiidled-p for sitvaailla-flavor 1 3 1 

Primary 103,108.110 

:proceed 122,123.126 

:refresh for tv:shect 109, 120 

:report 122,126 

»eBd-c<HiiinaBd for Igptbasic-lgp-ttreaa 1 1 3 

ncBd-coordinates for Igptbasic-lgp-stream 1 1 3 

:wbicb-operations for si:TanilIa-navor 1 3 1 

rwbo-lme-documentatioB-striBg 1 1 9 



Program Development Tools and Techmques 



171 



Symbolics, Inc 



Bexp^ Function 94 

Minibuffer 6 

aniniiBUBi-keight Init Option to trnuBunuB-wiadoir 

106 
iBiiiiimaBi-iridtli, Init Option to tTnaiiiiBiiB-wiMlow 106 
BinimuB-frindow, Flavor (in package tr:) 107 
Modes 9 

Modified Two Windows (c-x 4) 57 
[Modify] 95 
Modularity 103 
Mouse clicks 118 
Mouse documentation string 119 
Move To Previous Point (c-«-SPACE) 52 
Moving text 5 1 
Multiple 

Buffers 57 

Windows 57 
Multiple Edit Callers (m-x) 37 
Multiple List Callers (m-x) 37 
nnltiple-Talue, Special Form 107 



Name Last Kbd Macro (m-x) 
mil. Option to trace 87 



56 



Objects 28 

One Window (c-x i) 57 

Open Get Register (c-x g) 55 

:operatioB-luuidled-pk Method for ti:vJuulIa-flaTor 131 

Options 

:arg to trace 87 

:argpdl to trace 87 

:batcli to Bake-systm 71 

:bot]i to trace 87 

:break to trace 87. 91 

:c<Hid to trace 87 

:defaalt-uiit-plift to defflavor 106 

zdocnmentatioB to def flavor 129 

tentry to trace 87 

tentrycond to trace 87 

:eiitryprint to trace 87 

terror to trace 87, 91 

:exit to trace 87 

:exitbreak to trace 87, 91 

:exitc(Mid to trace 87 

:exitpriat to trace 87 

tfunctioB to tT:cbooce-TariabIe-Talaes 121 

:gettable-iiistaiice-Tariables to defflavor 103 

:iiiitable-iiistaiice-Tariablef to def flavor 1 1 2. 1 1 5 

:iiil to trace 87 

tpriat to trace 87 

trequired-flavort to def flavor 106 

:reqaired-metbodt to defflavor 103 

nrtep to trace 87, 89 

rvalue to trace 87 

:whereui to trace 87 
Other Window (c-x o) 57 



Packages 7,8,17,31,36 

Parentheses, Balancing 21 

Pathnames 37 

pkg-gotov Function 17 

plift. Function 32 

Primary methods 103, 108, 110 

[Print] 87 

[Print after] 87 

[Print before] 87 

Print Modifications (n-x) 50 

:priBt Option to trace 87 

:proceed. Method 122, 123. 126 

Proceed types 74, 122 

Proceeding 122 

:process; Init Option to tv:process-ttixia 1 18 

process-Bixu, Flavor (in package tv:) 118 

Processes 118,119 

prompt-aiid-read. Function 126 

Push Pop Point Explicit (m-SPACE) 52 

Put Regbter (c-x x) 55 

(^ery Replace (m-x) 5 1 
qnery-io^ Variable 126, 127 
Quick Arglist (c-sh-A) 36 
Quit(c-z) 74 

trefresh. Method for tvtdieet 109, 120 

Registers 55 

Reparse Attribute List (n-x) 9 

Replace (c-x) 51 

Replacing 50 

areport Method 122, 126 

:reqaired-flavori; Option to defflavor 1(^ 

treqaired-nethods; Option to defflavor 103 

Resources 115 

Restart handlers 74 

RESUKE 68, 89 

[Retry] 74 

RETURN 6 

[Return] 94,95 

Reverse Search (c-R) 5 1 

Save Position (c-x s) 52 

Save Region (m-w) 54 

Scroll Other Window (c-m-v) 57 

Searching 50 

Select All Buffers As Tag Table (m-x) 5 1 

Select Buffer (c-x b) 52 

SELECT E 7 
SELECT I 97 

Select Previous Buffer (c-m-L) 52 
Select System As Tag Table (m-x) 5 1 
»eBd-c<Mwnaiid, Method for lgp:basic-lgp-ftreaB 1 1 3 
send-coordiiiatcs; Method for lgp:bafic*lgp-streaai 113 
Set Backspace (m-x) 9 
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Set Base (n-x) 9 

Set Comment Column (c-x ;) 21 

Set Fill Column (c-x F) 10 

Set Fonts (m-x) 9 

Set Key (m-x) 56 

Set Lowercase (n-x) 9 

Set Nofill (m-x) 9 

Set Package (m-x) 9 

Set Patch File (m-x) 9 

Set Pop Mark (c-space) S2 

Set Tab Width (m-x) 9 

Set Vsp (m-x) 9 

sheet. Flavor (in package tr:) 127 

cheet-foUowuig-Uiiiker, Function (in package tr:) 127 

ti:fla¥or-alIoired-iBit-keywordi; Function 131 

tiiBafce-liardcopy-ttreafli, Function 116 

dtraBilla-fUiTor, Flavor 129 

ti:TiiiilU-fUTor Methods 

:operati<w-luuidlcd-p 131 

:vhkk-operatio« 131 
ngul. Function 102. 123. 126 
Signalling conditions 121 
Source Compare (m-x) 50 
Source Compare Merge (m-x) 50 

SPACE 6 

SPACE (Stepper command) 86 
Special commands (Debugger) 74 
Special Forms 

break 90 

■nltiple-Taiiie 107 

trace 86,89,91 

natrace 86, 87 

uawiad-protect 127 
[Split Screen] 58, 121 
Split Screen (m-x) 57 
•taadard-oatpnt. Variable 66 
Start Kbd Macro (c-x () 56 
[Step] 87,89 
ftep. Function 89 
»tep. Option to trace 87, 89 
Stepper 86 
Stepper commands 

c-B 88 

e-E 88 

c-N 86 

c-u 88 

c-x 88 

SPACE 86 

Stepping 66, 86 

SUSPEND 68 

Swap Point And Mark (c-x e-x) 52 

Symbob 30 

tytuiWrt, Flavor 1 1 9 



TAB (Indent For Lup) 21 
Tags Query Replace (m-x) 



51 



Tags Search (m-x) 51 
Tags tablM 50 

tenBiaal-io^ Variable 11, 101 
Text 

KiUing 52 

Moving 51 

Yanking 52 
[Trace] 85,89 
Trace (m-x) 85,89 
trace Options 

urg 87 

Uirgpdl 87 

:both 87 

:break 87.91 

xoaA 87 

reatry 87 

reatrycoiid 87 

reatrypriat 87 

:error 87, 91 

»xit 87 

:ezitbreak 87.91 

:ezitcoad 87 

rezitpriat 87 

out 87 

:priat 87 

Step 87,89 

tvalac 87 

:wliereia 87 
trace; Special Form 86, 89. 91 
Tracing 84 

tT»ay-tyi-adzia, Flavor 1 1 8 
tvauiy-tyi-adna Methods 

uay-tyi 119 
tTurhooce-TariaUe-Talaa; Function 1 1 4, 1 2 1 
tTukoose-variable-Talues Options 

:fiiactioB 121 
trrgraphicf-auxia. Flavor 106 
tT:grapliics-Bdxia Methods 

rdraw-liae 11.106 
tT:list-BM>afe-kattoas-Buxiii Flavor 1 1 8 
trauke-bliaker. Function 127 
traaake-wiadow. Function 102, 1 12. 1 15. 1 18 
tvaaiaiaraBHwiadow, Flavor 107 
tyaaiaiaiaM-wiadow Init Options 

:kliaker-p 106 

tedgce-froai 106 

»xpoce-p 106 

aaiaiaraai-height 106 

aaiaiaraai-widtk 106 
tvaaiaiBraia-wiadow Methods 

:inside-«iae 107 
tv:proceitHBdxiii^ Flavor 1 1 8 
trt^twesa-mixia Init Options 

tprocesB 118 
traheet Flavor 127 
tT»kcet Methods 
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tchange-of-tize-orHaargiw 109 

unit 109 

:refresli 109.120 
tTzsheet-foUowiiig-bliiiker, Function 127 
trzwindow. Flavor 102, 105, 106. 107 
Two Windows (c-x 2) 57 
tjpep^ Function 129 

unbreakoa, Function 90 
[Untrac«] 87 

tiBtrace. Special Form 86, 87 
nnwind-protect Special Form 127 
Up Comment Line (m-P) 20 
Update Attribute List (m-x) 9 

rvalue, Option to trace 87 

Taiaes, Variable 89 

Tanilla-flaTor, Flavor (in package fi:} 129 

Variables 32 

arglift 89 

qaery-io 126, 127 

standard-oatput 66 

termiaal-io 11, 101 

values 89 
View Directory (m-x) 38 
View Two Windows (c-x 3) 57 

wbat-filcs-call. Function 32 

Where Is Symbol (m-x) 3 1 

where-ii; Function 31 

[Wherein] 87 

twhereia, Option to trace 87 

twhich-operatioBi; Method for ti: vaailla-flavor 1 3 1 

wbo-calli; Function 32 

:w]io-liiie-docuiimtatioB-fftria( Method 119 

Whoppers 108 

window. Flavor (in package tv:) 102, 105, 106, 107 

Windows 

Choose variable values 1 14. 1 19 

Multiple 57 
witk-opeu-ftreaai^ Macro 116 

Yank(c.Y) 54 
Yank Pop (m-Y) 54 
Yanking text 52 



